home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / os2 / irit40e1.zip / IRIT.DOC < prev    next >
Text File  |  1994-01-05  |  193KB  |  4,777 lines
  1.  
  2.                                 INTRODUCTION
  3.                                 ------------
  4.  
  5.    IRIT is a solid modeler developed for educational purposes. Although
  6.  small, it is now powerful enough to create quite complex scenes.
  7.  
  8.    IRIT started as a polygonal solid modeler and was originally developed
  9.  on an IBM PC under MSDOS. Version 2.0 was also ported to X11 and version 3.0
  10.  to SGI 4D systems. Version 3.0 also includes quite a few free form curves
  11.  and surfaces tools. See the UPDATE.NEW file for more detailed update
  12.  information. In Version 4.0, the display devices were enhanced, freeform
  13.  curves and surfaces have further support, functions can be defined, and
  14.  numerous improvement and optimizations are added.
  15.  
  16.                                  COPYRIGHTS
  17.                                  ----------
  18.  
  19.    BECAUSE IRIT AND ITS SUPPORTING TOOLS AS DOCUMENTED IN THIS DOCUMENT
  20.  ARE LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT
  21.  PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING, I
  22.  GERSHON ELBER PROVIDE THE IRIT PROGRAM AND ITS SUPPORTING TOOLS "AS IS"
  23.  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  24.  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  25.  PARTICULAR PURPOSE.
  26.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THESE PROGRAMS IS WITH
  27.  YOU. SHOULD THE IRIT PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF
  28.  ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  29.  
  30.    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL GERSHON ELBER,
  31.  BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES,
  32.  OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
  33.  USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR A
  34.  FAILURE OF THE PROGRAMS TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY GERSHON
  35.  ELBER) THE PROGRAMS, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF
  36.  SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.
  37.  
  38.  
  39.    IRIT is a freeware solid modeler. It is not public domain since I
  40.  hold copyrights on it. However, unless you are to sell or attempt to make
  41.  money from any part of this code and/or any model you made with this solid
  42.  modeler, you are free to make anything you want with it.
  43.  
  44.    IRIT can be compiled and executed on numerous Unix systems as well
  45.  as OS2, Windows NT and AmigaDOS. However, beware the MSDOS support is fading
  46.  away.
  47.  
  48.    You are not obligated to me or to anyone else in any way by using IRIT.
  49.    You are encouraged to share any model you made with it, but the models
  50.  you made with it are yours, and you have no obligation to share them.
  51.    You can use this program and/or any model created with it for non
  52.  commercial and non profit purposes only. An acknowledgement on the way the
  53.  models were created would be nice but is not required.
  54.  
  55.                                     SETUP
  56.                                     -----
  57.  
  58.    The IRIT program reads a file called irit.cfg each time it is executed.
  59.    This file configures the system. It is a regular text file with comments, so
  60.  you can edit it and properly modify it for your environment.
  61.    This file is being searched for in the directory specified by the
  62.  IRIT_PATH environment variable.
  63.    For example 'setenv IRIT_PATH /u/gershon/irit/bin/'.
  64.    Note IRIT_PATH must terminate with '/'. If the variable is not set only
  65.  the current directory is being searched for irit.cfg.
  66.  
  67.    In addition, if it exists, a file by the name of iritinit.irt will be
  68.  automatically executed before any other '.irt' file. This file may contain
  69.  any IRIT command. It is the proper place to put your predefined
  70.  functions and procedures if you have some.
  71.    This file will be searched much the same way IRIT.CFG is. The
  72.  name of this initialization file may be changed by setting the StartFile
  73.  entry in the configuration file.
  74.    This file is far more important starting at version 4.0, because of the new
  75.  function and procedure definition that has been added, and which is used
  76.  to emulate BEEP, VIEW, and INTERACT for example.
  77.  
  78.    The solid modeler can be executed in text mode (see the .cfg and the -t
  79.  flag below) on virtually any system with a C compiler.
  80.  
  81.   Under all systems the following environment variables must be set
  82.  and updated:
  83.  
  84.     path           Add to path the directory where IRIT's binaries are.
  85.     IRIT_PATH      Directory with config., help and IRIT's binary files.
  86.     IRIT_DISPLAY   The graphics driver program/options. Must be in path.
  87.     IRIT_BIN_IPC   If set, uses binary Inter Process Communication.
  88.  
  89.  
  90.  For example,
  91.  
  92.    set path = (path /u/gershon/irit/bin)
  93.    setenv IRIT_PATH  /u/gershon/irit/bin/
  94.    setenv IRIT_DISPLAY "xgldrvs -s-"
  95.    setenv IRIT_BIN_IPC 1
  96.  
  97.  to set /u/gershon/irit/bin as the binary directory and to use the sgi's
  98.  gl driver. If IRIT_DISPLAY is not set, the server (i.e., the IRIT
  99.  program) will prompt and wait for you to run a client (i.e., a display
  100.  driver). if IRIT_PATH is not set, none of the configuration files, nor
  101.  the help file will be found.
  102.  
  103.  If IRIT_BIN_IPC is not set, text based IPC is used, which is far
  104.  slower. No real reason not to use IRIT_BIN_IPC, unless it does not
  105.  work for you.
  106.  
  107.   In addition, the following optional environment variables may be set.
  108.  
  109.     IRIT_MALLOC       If set, apply dynamic memory consistency testing.
  110.    
  111.                   Programs will execute much slower in this mode.
  112.     IRIT_DEBUG_FUNC   prints debugging information on user's defined
  113.    
  114.                   functions. If >0, invocation and leaving of functions.
  115.                       If >2, parameters and returned values as well. If >4
  116.    
  117.                   global variable list is printed as well on invocation.
  118.     IRIT_SERVER_HOST  Internet Name of IRIT server (used by graphics driver).
  119.     IRIT_SERVER_PORT  Set a different socket port number than the default.
  120.  
  121.  
  122.  For example,
  123.  
  124.    setenv IRIT_MALLOC 1
  125.    setenv IRIT_SERVER_HOST irit.cs.technion.ac.il
  126.    setenv IRIT_SERVER_PORT 5432
  127.  
  128.  IRIT_MALLOC is useful for programmers, or when reporting a memory
  129.  fatal error occurrence. The IRIT_SERVER_HOST/PORT controls the
  130.  server/client (IRIT/Display device) communication.
  131.  
  132.  IRIT_SERVER_HOST and IRIT_SERVER_PORT are used in the unix and
  133.  Window NT ports of IRIT.
  134.  
  135.    See the section on the graphics drivers for more details.
  136.  
  137.    A session can be logged into a file as set via LogFile in the configuration
  138.  file. See also the LOGFILE command.
  139.  
  140.    The following command line options are available:
  141.  
  142.    IRIT [-t] [-z] [file.irt]
  143.  
  144.  
  145.     -t          Puts IRIT into text mode. No graphics will be displayed and
  146.                 the display commands will be ignored. Useful when one needs to
  147.                 execute an irt file to create data on a tty device...
  148.     -z          Prints usage message and current configuration/version
  149.                 information.
  150.     file.irt    A file to invoke directly instead of waiting to input from
  151.                 stdin. 
  152.  
  153.  
  154.  
  155.  Under OS2 the IRIT_DISPLAY environment variable must be set (if set) to
  156.  os2drvs.exe without any option (-s- will be passed automatically).
  157.  os2drvs.exe must be in a directory that is in the PATH environment
  158.  variable. IRIT_POS can be set to the X1 Y1 X2 Y2 dimensions of the
  159.  window. IRIT_BIN_IPC can be used to signal binary IPC which is faster.
  160.  Here is a complete example:
  161.  
  162.  set IRIT_PATH=c:\irit\bin\
  163.  set IRIT_DISPLAY=os2drvs.exe
  164.  set IRIT_POS=230 120 550 460
  165.  set IRIT_BIN_IPC=1
  166.  
  167.  assuming the directory specified by IRIT_PATH holds the executables of
  168.  IRIT and is in PATH.
  169.  
  170.  If IRIT_BIN_IPC is not set, text based IPC is used which is far
  171.  slower. No real reason not to use IRIT_BIN_IPC unless it does not
  172.  work for you.
  173.  
  174.  
  175.  The NT port uses sockets and is, in this respect, similar to the unix port.
  176.  The envirnoment variables IRIT_DISPLAY, IRIT_SERVER_HOST,
  177.  IRIT_SERVER_PORT, and IRIT_BIN_IPC should all be set in a similar
  178.  way to the Unix specific setup. As a direct result, the server (IRIT)
  179.  and the display device may be running on different hosts. For example
  180.  the server might be running on an NT system while the display device
  181.  will be running on an SGI4D exploiting the graphic's hardware
  182.  capabilities.
  183.  
  184.    Under UNIX using X11 (x11drvs driver) add the following options to
  185.  your .Xdefaults. Most are self explanatory. The Trans attributes control
  186.  the transformation window, while the View attributes control the view window.
  187.  SubWin attributes control the subwindows within the Transformation window.
  188.  
  189.     #if COLOR                                                        
  190.     irit*Trans*BackGround:            NavyBlue                       
  191.     irit*Trans*BorderColor:           Red                            
  192.     irit*Trans*BorderWidth:           3                              
  193.     irit*Trans*TextColor:             Yellow                         
  194.     irit*Trans*SubWin*BackGround:     DarkGreen                      
  195.     irit*Trans*SubWin*BorderColor:    Magenta                        
  196.     irit*Trans*Geometry:              =150x500+500+0                 
  197.     irit*Trans*CursorColor:           Green                          
  198.     irit*View*BackGround:             NavyBlue                       
  199.     irit*View*BorderColor:            Red                            
  200.     irit*View*BorderWidth:            3                              
  201.     irit*View*Geometry:               =500x500+0+0                   
  202.     irit*View*CursorColor:            Red                            
  203.     irit*MaxColors:                   15                             
  204.     #else                                                            
  205.     irit*Trans*Geometry:              =150x500+500+0                 
  206.     irit*Trans*BackGround:            Black                          
  207.     irit*View*Geometry:               =500x500+0+0                   
  208.     irit*View*BackGround:             Black                          
  209.     irit*MaxColors:                   1                              
  210.     #endif                                                           
  211.  
  212.  
  213.                                  FIRSTUSAGE
  214.                                  ----------
  215.  
  216.    Commands to IRIT are entered using a textual interface, usually
  217.  from the same window the program was executed from.
  218.  
  219.    Some important commands to begin with are,
  220.  
  221.    1. include("file.irt"); - will execute the commands in file.irt. Note
  222.       include can be recursive up to 10 levels. To execute the demo
  223.       (demo.irt) simply type 'include("demo.irt");'. Another way to run
  224.       the demo is by typing demo(); which is a predefined procedure defined
  225.       in iritinit.irt.
  226.  
  227.    2. help(""); - will print all available commands and how to get help on
  228.       them. A file called irit.hlp will be searched as irit.cfg is
  229.       being searched (see above), to provide the help.
  230.  
  231.    3. exit(); - close everything and exit IRIT.
  232.  
  233.    Most operators are overloaded. This means that you can multiply
  234.  two scalars (numbers), or two vectors, or even two matrices, with the same
  235.  multiplication operator (*). To get the on-line help on the
  236.  operator '*' type 'help("*");'
  237.  
  238.    The best way to learn this program (like any other program...) is by
  239.  trying it. Print the manual and study each of the commands available.
  240.    Study the demo programs (*.irt) provided as well.
  241.  
  242.    The "best" mode to use irit is via the emacs editor. With this distribution
  243.  an emacs mode for irit files (irt postfix) is provided (irit.el). Make your
  244.  .emacs load this file automatically. Loading file.irt will switch emacs into
  245.  Irit mode that supports the following three keystrokes:
  246.  
  247.     Meta-E             Executes the current line
  248.     Meta-R             Executes the current Region (Between Cursor and Mark)
  249.     Meta-S             Executes a single line from input buffer
  250.  
  251.    The first time one of the above keystrokes is hit, emacs will fork an Irit
  252.  process so that Irit's stdin is controlled via the above commands.
  253.    This emacs mode was tested under various unix environments and under OS2
  254.  2.x.
  255.  
  256.                                   DATATYPES
  257.                                   ---------
  258.   These are the Data Types recognized by the solid modeler. They are also
  259.  used to define the calling sequences of the different functions below:
  260.  
  261.     ConstantType       Scalar real type that cannot be modified.
  262.     NumericType        Scalar real type.
  263.     VectorType         3D real type vector.
  264.     PointType          3D real type point.
  265.     CtlPtType          Control point of a freeform curve or surface.
  266.     MatrixType         4 by 4 matrix (homogeneous transformation matrix).
  267.     PolygonType        Object consists of polygons.
  268.     PolylineType       Object consists of polylines.
  269.     CurveType          Object consists of curves.
  270.     SurfaceType        Object consists of surfaces.
  271.     GeometricType      One of Polygon/lineType, CurveType, SurfaceType.
  272.     GeometricTreeType  A list of GeometricTypes or GeometricTreeTypes.
  273.     StringType         Sequence of chars within double quotes - "A string".
  274.                        Current implementation is limited to 80 chars.
  275.     AnyType            Any of the above.
  276.     ListType           List of (any of the above type) objects. List 
  277.                        size is dynamically increased, as needed.
  278.  
  279.   Although points and vectors are not the same, IRIT does not
  280.  destinguish between them, most of the time. This might change in the future.
  281.  
  282.                                   COMMANDS
  283.                                   --------
  284.  
  285.  These are all the commands and operators supported by the IRIT solid
  286.  modeler:
  287.  
  288.  
  289.     +          BOOLSUM    CONVEX     GBOX       PROCEDURE  SREFINE   
  290.     -          BOX        COORD      GPOLYGON   ROTX       SREGION   
  291.     *          BSP2BZR    COS        GPOLYLINE  ROTY       STANGENT  
  292.     /          BZR2BSP    COMPOSE    HELP       ROTZ       SURFREV   
  293.     ^          CBEZIER    CPOLY      HOMOMAT    RULEDSRF   SWEEPSRF  
  294.     =          CBSPLINE   CRAISE     IF         SAVE       SYMBCPROD 
  295.     ==         CCINTER    CREFINE    INCLUDE    SBEZIER    SYMBDIFF  
  296.     !=         CCRVTR     CREGION    INTERACT   SBSPLINE   SYMBDPROD 
  297.     <          CDERIVE    CROSSEC    LIST       SCALE      SYMBPROD  
  298.     >          CDIVIDE    CRVLNDST   LISTSIZE   SDERIVE    SYMBSUM   
  299.     <=         CEDITPT    CRVPTDST   LN         SDIVIDE    SYSTEM    
  300.     >=         CEVAL      CSURFACE   LOAD       SEDITPT    TAN       
  301.     ABS        CEXTREMES  CTANGENT   LOG        SEVAL      TIME      
  302.     ACOS       CHDIR      CTLPT      LOGFILE    SFROMCRVS  THISOBJ   
  303.     ADAPISO    CINFLECT   CYLIN      MERGEPOLY  SIN        TORUS     
  304.     ARC        CIRCLE     CZEROS     NIL        SMERGE     TRANS     
  305.     AREA       CIRCPOLY   EXIT       NTH        SMORPH     VARLIST   
  306.     ASIN       CMESH      EXP        OFFSET     SNOC       VECTOR    
  307.     ATAN       COERCE     EXTRUDE    PAUSE      SNORMAL    VIEW      
  308.     ATAN2      COLOR      FFCOMPAT   PDOMAIN    SNRMLSRF   VIEWOBJ   
  309.     ATTRIB     COMMENT    FOR        POLY       SPHERE     VOLUME    
  310.     AOFFSET    CON2       FREE       PRINTF     SQRT                 
  311.     BOOLONE    CONE       FUNCTION   PRISA      SRAISE               
  312.  
  313.  
  314.                                   FUNCTIONS
  315.                                   ---------
  316.  
  317.  Functions that return a NumericType:
  318.  
  319.     ABS        ATAN       EXP        SIN        VOLUME    
  320.     ACOS       ATAN2      LISTSIZE   SQRT                 
  321.     AREA       COS        LN         TAN                  
  322.     ASIN       CPOLY      LOG        THISOBJ              
  323.  
  324.  
  325.  Functions that return a GeometricType:
  326.  
  327.     ADAPISO    CDIVIDE    COORD      EXTRUDE    SBEZIER    SREFINE   
  328.     ARC        CEDITPT    CPOLY      FFCOMPAT   SBSPLINE   SREGION   
  329.     AOFFSET    CEVAL      CRAISE     GBOX       SDERIVE    STANGENT  
  330.     BOOLONE    CEXTREMES  CREFINE    GPOLYGON   SDIVIDE    SURFREV   
  331.     BOOLSUM    CINFLECT   CREGION    GPOLYLINE  SEDITPT    SWEEPSRF  
  332.     BOX        CIRCLE     CROSSEC    MERGEPOLY  SEVAL      SYMBCPROD 
  333.     BSP2BZR    CIRCPOLY   CRVLNDST   NIL        SFROMCRVS  SYMBDIFF  
  334.     BZR2BSP    CMESH      CRVPTDST   OFFSET     SMERGE     SYMBDPROD 
  335.     CBEZIER    COERCE     CSURFACE   PDOMAIN    SMORPH     SYMBPROD  
  336.     CBSPLINE   COMPOSE    CTANGENT   POLY       SNORMAL    SYMBSUM   
  337.     CCINTER    CON2       CTLPT      PRISA      SNRMLSRF   TORUS     
  338.     CCRVTR     CONE       CYLIN      PROCEDURE  SPHERE               
  339.     CDERIVE    CONVEX     CZEROS     RULEDSRF   SRAISE               
  340.  
  341.  
  342.  Functions that create linear transformation matrices:
  343.  
  344.     HOMOMAT    ROTX       ROTY       ROTZ       SCALE      TRANS     
  345.  
  346.  
  347.  Miscellaneous functions:
  348.  
  349.     ATTRIB     FOR        INCLUDE    NTH        SNOC       VIEW      
  350.     CHDIR      FREE       INTERACT   PAUSE      SYSTEM     VIEWOBJ   
  351.     COLOR      FUNCTION   LIST       PRINTF     TIME                 
  352.     COMMENT    HELP       LOAD       PROCEDURE  VARLIST              
  353.     EXIT       IF         LOGFILE    SAVE       VECTOR               
  354.  
  355.  
  356.  Variables that are predefined in the system:
  357.  
  358.     AXES       DUMPLVL    INTERCRV   PRSP_MAT             
  359.     COPLANAR   ECHOSRC    MACHINE    RESOLUTION           
  360.     DRAWCTLPT  FLAT4PLY   POLYSORT   VIEW_MAT             
  361.  
  362.  
  363.  Constants that are predefined in the system:
  364.  
  365.     APOLLO     E2         KV_FLOAT   ON         ROW        WHITE     
  366.     BLACK      E3         KV_OPEN    P2         SGI        YELLOW    
  367.     BLUE       FALSE      MAGENTA    P3         SUN                  
  368.     COL        GREEN      MSDOS      PI         TRUE                 
  369.     CYAN       HP         OFF        RED        UNIX                 
  370.  
  371.  
  372.                                   LANGUAGE
  373.                                   --------
  374.     The front end of the IRIT solid modeler is an infix parser that
  375.  mimics some of the C language behavior. The infix operators that are supported
  376.  are plus (+), minus (-), multiply (*), divide (/), and power (^), for
  377.  numeric operators, with the same precedence as in C.
  378.  
  379.     However, unlike the C language, these operators are overloaded,
  380.  or different action is taken, based upon the different operands.
  381.    This means that one can write '1 + 2', in which the plus sign denotes a
  382.  numeric addition, or one can write 'PolyObj1 + PolyObj2', in which case the
  383.  plus sign denotes the Boolean operation of a union between two geometric
  384.  objects.
  385.    The exact way each operator is overloaded is defined below.
  386.  
  387.    In this environment, reals, integers, and even Booleans, are all represented
  388.  as real types. Data are automatically promoted as necessary.
  389.    For example, the constants TRUE and FALSE are defined as 1.0 and 0.0
  390.  respectively.
  391.  
  392.    Each expression is terminated by a semicolon. An expression can be as
  393.  simple as 'a;' which prints the value of variable a, or as complex as:
  394.  
  395.     for ( t = 1.1, 0.1, 1.9,
  396.             cb1 = csurface( sb, COL, t ):
  397.             color( cb1, green ):
  398.             snoc( cb1, cb_all )
  399.         );
  400.  
  401.    While an expression is terminated with a semicolon, a colon is used to
  402.  terminate mini-expressions within an expression.
  403.  
  404.    Once a complete expression is read in (i.e., a semicolon is detected)
  405.  and parsed correctly (i.e. no syntax errors are found), it is executed.
  406.    Before each operator or a function is executed, parameter type matching
  407.  tests are made to make sure the operator can be applied to these
  408.  operand(s), or that the function gets the correct set of arguments.
  409.  
  410.    The parser is totally case insensitive, so Obj, obj, and OBJ will refer
  411.  to the same object, while MergePoly, MERGEPOLY, and mergePoly will refer
  412.  to the same function.
  413.  
  414.    Objects (Variables if you prefer) need not be declared. Simply use them
  415.  when you need them. Object names may be any alpha-numeric (and underscore)
  416.  string of at most 30 characters. By assigning to an old object, the old
  417.  object will be automatically deleted and if necessary its type will be
  418.  modified on the fly.
  419.  
  420.  Example:
  421.  
  422.     V = sin( 45 * pi / 180.0 );
  423.     V = V * vector( 1, 2, 3 );
  424.     V = V * rotx( 90 );
  425.     V = V * V;
  426.  
  427.  will assign to V a NumericType equal to the sine of 45 degrees, the VectorType
  428.  ( 1, 2, 3 ) scaled by the sine of 45, rotate that vector around the X axis
  429.  by 90 degrees, and finally a NumericType which is the dot (inner) product of
  430.  V with itself.
  431.  
  432.    The parser will read from stdin, unless a file is specified on the command
  433.  line or an INCLUDE command is executed. In both cases, when the end of file
  434.  is encountered, the parser will again wait for input from stdin. In order
  435.  to execute a file and quit in the end of the file, put an EXIT command as
  436.  the last command in the file.
  437.  
  438.                                       +
  439.                                       -
  440.  The + operator is overloaded above the following domains:
  441.  
  442.   NumericType + NumericType -> NumericType
  443.   VectorType  + VectorType  -> VectorType   (Vector addition)
  444.   MatrixType  + MatrixType  -> MatrixType   (Matrix addition)
  445.   PolygonType + PolygonType -> PolygonType  (Boolean UNION operation)
  446.   CurveType   + CurveType   -> CurveType    (Curve curve profiling)
  447.   CurveType   + CtlPtType   -> CurveType    (Curve control point profiling)
  448.   CtlPtType   + CtlPtType   -> CurveType    (Control points profiling)
  449.   ListType    + ListType    -> ListType     (Append lists operator)
  450.   StringType  + StringType  -> StringType   (String concat)
  451.   StringType  + RealType    -> StringType   (String concat, real as int string)
  452.  
  453.  Note: Boolean UNION of two disjoint objects (no common volume) will result
  454.  with the two objects combined. It is the USER responsibility to make sure that
  455.  the non intersecting objects are also disjoint - this system only tests for
  456.  no intersection.
  457.  
  458.                                       -
  459.                                       -
  460.  The - operator is overloaded above the following domains:
  461.  
  462.  As a binary operator:
  463.  
  464.   NumericType - NumericType -> NumericType
  465.   VectorType  - VectorType  -> VectorType   (Vectoric difference)
  466.   MatrixType  - MatrixType  -> MatrixType   (Matrix difference) 
  467.   PolygonType - PolygonType -> PolygonType  (Boolean SUBTRACT operation)
  468.  
  469.  As a unary operator:
  470.  
  471.   - NumericType -> NumericType
  472.   - VectorType  -> VectorType    (Scale vector by -1)
  473.   - MatrixType  -> MatrixType    (Scale matrix by -1)
  474.   - PolygonType -> PolygonType   (Boolean NEGATION operation)
  475.   - CurveType   -> CurveType     (Curve parameterization is reversed)
  476.   - SurfaceType -> SurfaceType   (Surface parameterization is reversed)
  477.  
  478.  Note: Boolean SUBTRACT of two disjoint objects (no common volume) will result
  479.  with an empty object. For both a curve and a surface parameterization, reverse
  480.  operation (binary minus) causes the object normal to be flipped as a side
  481.  effect.
  482.  
  483.                                       *
  484.                                       -
  485.  The * operator is overloaded above the following domains:
  486.  
  487.   NumericType * NumericType   -> NumericType
  488.   VectorType  * NumericType   -> VectorType    (Vector scaling)
  489.   VectorType  * VectorType    -> NumericType   (Inner product)
  490.   MatrixType  * NumericType   -> MatrixType    (Matrix Scaling)
  491.   MatrixType  * VectorType    -> VectorType    (Vector transformation)
  492.   MatrixType  * MatrixType    -> MatrixType    (Matrix multiplication)
  493.   MatrixType  * GeometricType -> GeometricType (Object transformation)
  494.   MatrixType  * ListType      -> ListType      (Object hierarchy transform.)
  495.   PolygonType * PolygonType   -> PolygonType   (Boolean INTERSECTION operation)
  496.  
  497.  Note: Boolean INTERSECTION of two disjoint objects (no common volume) will
  498.  result with an empty object. Object hierarchy transform transforms any
  499.  transformable object (GeometricType) found in the list recursively.
  500.  
  501.                                       /
  502.                                       -
  503.  The / operator is overloaded above the following domains:
  504.  
  505.   NumericType / NumericType -> NumericType
  506.   PolygonType / PolygonType -> PolygonType   (Boolean CUT operation)
  507.  
  508.  Note: Boolean CUT of two disjoint objects (no common volume) will result
  509.  with an empty object.
  510.  
  511.                                       ^
  512.                                       -
  513.  The ^ operator is overloaded above the following domains:
  514.  
  515.   NumericType ^ NumericType -> NumericType
  516.   VectorType  ^ VectorType  -> VectorType  (Cross product)
  517.   MatrixType  ^ NumericType -> MatrixType  (Matrix to the (int) power)
  518.   PolygonType ^ PolygonType -> PolygonType (Boolean MERGE operation)
  519.   StringType  ^ StringType  -> StringType  (String concat)
  520.   StringType  ^ RealType    -> StringType  (String concat, real as real string)
  521.  
  522.  Note: Boolean MERGE simply merges the two sets of polygons without any
  523.  intersection tests. Matrix powers must be positive integers or -1, in which
  524.  case the matrix inverse (if it exists) is computed.
  525.  
  526.                                       =
  527.                                       -
  528.    Assignments are allowed as side effects, in any place in an expression.
  529.  If "Expr" is an expression, then "var = Expr" is the exact same expression
  530.  with the side effect of setting Var to that value. There is no guarantee
  531.  on the order of evaluation, so using Vars that are set within the same
  532.  expression is a bad practice. Use parentheses to force the order of
  533.  evaluation, i.e., "( var = Expr )".
  534.  
  535.                   Comparison operators ==, !=, <, >, <=, >=
  536.                   -----------------------------------------
  537.  The conditional comparison operators can be applied to the following
  538.  domains (o for a comparison operator):
  539.  
  540.   NumericType o NumericType -> NumericType
  541.   StringType  o StringType  -> NumericType
  542.   PointType   o PointType   -> NumericType
  543.   VectorType  o VectorType  -> NumericType
  544.   PlaneType   o PlaneType   -> NumericType
  545.  
  546.  The returned NumericType is non-zero if the condition holds, or zero if
  547.  not.
  548.    For PointTypes, VectorTypes, and PlaneTypes, only == and != comparisons
  549.  are valid. This is either the same or different.
  550.    For NumericTypes and StringTypes (uses strcmp) all comparisons are valid.
  551.  
  552.                          Logical operators &&, ||, !
  553.                          ---------------------------
  554.  Complex logical expressions can be defined using the logical and (&&),
  555.  logical or (||) and logical not (!). These operators can be applied
  556.  to NumericTypes that are considered Boolean results. That is, true for a
  557.  non-zero value, and false otherwise.
  558.    The returned NumericType is true if both operands are true for the and
  559.  operator, at least one is true for the or operator, and the operand is
  560.  false for the not operator. In all other cases, a false is returned.
  561.    To make sure Logical expressions are readable, the and and or
  562.  operators are defined to have the same priority. Use parentheses to
  563.  disambiguate a logical expression and to make it more readable.
  564.  
  565.                             Priority of operators
  566.                             ---------------------
  567.    The following table lists the priority of the different operators.
  568.  
  569.     Lowest             Operator           Name of operator  
  570.     priority           ,                  comma             
  571.                        :                  colon             
  572.                        &&, ||             logical and, logical or
  573.                        =,==,!=,<=,>=,<,>  assignment, equal, not equal, less
  574.                                           equal, greater equal, less, greater
  575.                        +, -               plus, minus       
  576.                        *, /               multiply, divide  
  577.     Highest            ^                  power             
  578.     priority           -, !               unary minus, logical not
  579.  
  580.  
  581.                                    Grammar
  582.                                    -------
  583.    The grammar of the IRIT parser follows similar guidelines as
  584.  the C language for simple expressions. However, complex statements differ.
  585.    See the IF, FOR, FUNCTION, and PROCEDURE below for the usage of these
  586.  clauses.
  587.  
  588.                             Function Description
  589.                             --------------------
  590.  
  591.                        NumericType returning functions
  592.                        -------------------------------
  593.  
  594.                                      ABS
  595.                                      ---
  596.  
  597.  NumericType ABS( NumericType Operand )
  598.  
  599.    Returns the absolute value of the given Operand.
  600.  
  601.                                     ACOS
  602.                                     ----
  603.  
  604.  NumericType ACOS( NumericType Operand )
  605.  
  606.    Returns the arc cosine value (in radians) of the given Operand.
  607.  
  608.                                     AREA
  609.                                     ----
  610.  
  611.  NumericType AREA( PolygonType Object )
  612.  
  613.    Returns the area of the given Object (in object units). Returned is
  614.  the area of the polygonal object, not the area of the primitive it might
  615.  approximate.
  616.  
  617.    This means that the area of a polygonal approximation of a sphere will be
  618.  returned, not the exact area of the sphere.
  619.  
  620.                                     ASIN
  621.                                     ----
  622.  
  623.  NumericType ASIN( NumericType Operand )
  624.  
  625.    Returns the arc sine value (in radians) of the given Operand.
  626.  
  627.                                     ATAN
  628.                                     ----
  629.  
  630.  NumericType ATAN( NumericType Operand )
  631.  
  632.    Returns the arc tangent value (in radians) of the given Operand.
  633.  
  634.                                     ATAN2
  635.                                     -----
  636.  
  637.  NumericType ATAN2( NumericType Operand1, NumericType Operand2 )
  638.  
  639.    Returns the arc tangent value (in radians) of the given ratio:
  640.  Operand1 / Operand2, over the whole circle.
  641.  
  642.                                      COS
  643.                                      ---
  644.  
  645.  NumericType COS( NumericType Operand )
  646.  
  647.    Returns the cosine value of the given Operand (in radians).
  648.  
  649.                                     CPOLY
  650.                                     -----
  651.  
  652.  NumericType CPOLY( PolygonType Object )
  653.  
  654.    Returns the number of polygons in the given polygonal Object.
  655.  
  656.                                      EXP
  657.                                      ---
  658.  
  659.  NumericType EXP( NumericType Operand )
  660.  
  661.    Returns the natural exponent value of the given Operand.
  662.  
  663.                                   LISTSIZE
  664.                                   --------
  665.  
  666.  NumericType LISTSIZE( ListType List | PolyType Poly )
  667.  
  668.    Returns the length of a list, if List, or the number of polygons
  669.  if Poly. If, however, only one polygon is in Poly, it returns
  670.  the number of vertices in that polygon.
  671.  
  672.  Example:
  673.  
  674.    len = LISTSIZE( list( 1, 2, 3 ) );
  675.    numPolys = LISTSIZE( axes );
  676.  
  677.  will assign the value of 3 to the variable len, and set numPolys
  678.  to the number of polylines in the axes object.
  679.  
  680.                                      LN
  681.                                      --
  682.  
  683.  NumericType LN( NumericType Operand )
  684.  
  685.    Returns the natural logarithm value of the given Operand.
  686.  
  687.                                      LOG
  688.                                      ---
  689.  
  690.  NumericType LOG( NumericType Operand )
  691.  
  692.    Returns the base 10 logarithm value of the given Operand.
  693.  
  694.                                      SIN
  695.                                      ---
  696.  
  697.  NumericType SIN( NumericType Operand )
  698.  
  699.    Returns the sine value of the given Operand (in radians).
  700.  
  701.                                     SQRT
  702.                                     ----
  703.  
  704.  NumericType SQRT( NumericType Operand )
  705.  
  706.    Returns the square root value of the given Operand.
  707.  
  708.                                      TAN
  709.                                      ---
  710.  
  711.  NumericType TAN( NumericType Operand )
  712.  
  713.    Returns the tangent value of the given Operand (in radians).
  714.  
  715.                                    THISOBJ
  716.                                    -------
  717.  
  718.  NumericType THISOBJ( AnyType Object )
  719.  
  720.    Returns the object type of the given Object. This can be one of
  721.  the constants NUMERIC_TYPE, STRING_TYPE, VECTOR_TYPE, POINT_TYPE,
  722.  CTLPT_TYPE, MATRIX_TYPE, POLY_TYPE, CURVE_TYPE, or SURFACE_TYPE.
  723.  
  724.                                    VOLUME
  725.                                    ------
  726.  
  727.  NumericType VOLUME( PolygonType Object )
  728.  
  729.    Returns the volume of the given Object (in object units). It returns
  730.  the volume of the polygonal object, not the volume of the object it might
  731.  approximate.
  732.  
  733.    This routine decomposes all non-convex polygons to convex ones as a side
  734.  effect (see CONVEX).
  735.  
  736.  
  737.                       GeometricType returning functions
  738.                       ---------------------------------
  739.  
  740.                                    ADAPISO
  741.                                    -------
  742.  
  743.  CurveType ADAPISO( SurfaceType Srf, NumericType Dir, NumericType Eps,
  744.                     NumericType FullIso, NumericType SinglePath )
  745.  
  746.  Constructs a coverage to Srf using isocurve in the Dir direction,
  747.  so that for any point p on surface Srf, there exists a point on one of
  748.  the isocurves that is close to p within Eps. If FullIso, the
  749.  extracted isocurves span the entire surface domain, otherwise they may
  750.  span only a subset of the domain. If SinglePath, an approximation to
  751.  a single path (Hamiltonian path) that visits all isocurves is constructed.
  752.  
  753.     srf = sbezier( list( list( ctlpt( E3, -0.5, -1.0,  0.0 ),
  754.                                ctlpt( E3,  0.4,  0.0,  0.1 ),
  755.                                ctlpt( E3, -0.5,  1.0,  0.0 ) ),
  756.                          list( ctlpt( E3,  0.0, -0.7,  0.1 ),
  757.                                ctlpt( E3,  0.0,  0.0,  0.0 ),
  758.                                ctlpt( E3,  0.0,  0.7, -0.2 ) ),
  759.                          list( ctlpt( E3,  0.5, -1.0,  0.1 ),
  760.                                ctlpt( E3, -0.4,  0.0,  0.0 ),
  761.                                ctlpt( E3,  0.5,  1.0, -0.2 ) ) ) );
  762.     aiso = ADAPISO( srf, COL, 0.1, FALSE, FALSE );
  763.  
  764.  Constructs an adaptive isocurve approximation with tolerance of 0.1 to
  765.  surface srf in direction COL. Isocurves are allowed to span a
  766.  subset of the surface domain. No single path is needed.
  767.  
  768.  The SinglePath option is currently not supported.
  769.                                      ARC
  770.                                      ---
  771.  
  772.  CurveType ARC( VectorType StartPos, VectorType Center, VectorType EndPos )
  773.  
  774.  Constructs an arc between the two end points StartPos and EndPos,
  775.  centered at Center. Arc will always be less than 180 degrees, so the
  776.  shortest circular path from StartPos to EndPos is selected. The
  777.  case where StartPos, Center, and EndPos are collinear is
  778.  illegal, since it attempts to define a 180 degrees arc. Arc is constructed
  779.  as a single rational quadratic Bezier curve.
  780.  
  781.  Example:
  782.  
  783.     Arc1 = ARC( vector( 1.0, 0.0, 0.0 ),
  784.                 vector( 1.0, 1.0, 0.0 ),
  785.                 vector( 0.0, 1.0, 0.0 ) );
  786.  
  787.  constructs a 90 degrees arc, tangent to both the X and Y axes at coordinate 1.
  788.  
  789.                                    AOFFSET
  790.                                    -------
  791.  
  792.  CurveType AOFFSET( CurveType Crv, NumericType OffsetDistance,
  793.                     NumericType Epsilon, NumericType TrimLoops )
  794.  
  795.  or
  796.  
  797.  SurfaceType AOFFSET( SurfaceType Srf NumericType OffsetDistance,
  798.                       NumericType Epsilon, NumericType TrimLoops )
  799.  
  800.  Computes an offset of OffsetDistance with globally bounded error
  801.  (controlled by Epsilon). The smaller Epsilon is, the better
  802.  the approximation to the offset. The bounded error is achieved by adaptive
  803.  refinement of the Crv.
  804.    If TrimLoops is TRUE or on, the regions of the object that
  805.  self-intersect as a result of the offset operation are trimmed away.
  806.  
  807.  Example:
  808.  
  809.  OffCrv = AOFFSET( Crv, 0.5, 0.03, TRUE );
  810.  
  811.  computes an adaptive offset to Crv with OffsetDistance of
  812.  0.5 and Epsilon of 0.03 and trims the self-intersection loops.
  813.  See also OFFSET.
  814.  
  815.                                    BOOLONE
  816.                                    -------
  817.  
  818.  SurfaceType BOOLONE( CurveType Crv )
  819.  
  820.  Given a closed curve, the curve is subdivided into four segments equally
  821.  spaced in the parametric space that are fed into BOOLSUM. Useful if
  822.  a surface should "fill" the area enclosed by a closed curve.
  823.  
  824.  Example:
  825.  
  826.  Srf = BOOLONE( circle( vector( 0.0, 0.0, 0.0 ), 1.0 ) );
  827.  
  828.  Creates a disk surface containing the area enclosed by the unit circle.
  829.  
  830.                                    BOOLSUM
  831.                                    -------
  832.  
  833.  SurfaceType BOOLSUM( CurveType Crv1, CurveType Crv2,
  834.                       CurveType Crv3, CurveType Crv4 )
  835.  
  836.  Construct a surface using the provided four curves as its four boundary
  837.  curves. Curves do not have to have the same order or type, and will be
  838.  promoted to their least common denominator. The end points of the four
  839.  curves should match as follows:
  840.  
  841.     Crv1 start point,              to Crv3 start point.        
  842.     Crv1 end point,                to Crv4 start point.        
  843.     Crv2 start point,              to Crv3 end point.          
  844.     Crv2 end point,                to Crv4 end point.          
  845.  
  846.  where Crv1 and Crv2 are the two boundaries in one parametric
  847.  direction, and Crv3 and Crv4 are the two boundaries in the other
  848.  parametric direction.
  849.  
  850.  Example:
  851.  
  852.     Cbzr1 = cbezier( list( ctlpt( E3, 0.1, 0.1, 0.1 ),
  853.                            ctlpt( E3, 0.0, 0.5, 1.0 ),
  854.                            ctlpt( E3, 0.4, 1.0, 0.4 ) ) );
  855.     Cbzr2 = cbezier( list( ctlpt( E3, 1.0, 0.2, 0.2 ),
  856.                            ctlpt( E3, 1.0, 0.5, -1.0 ),
  857.                            ctlpt( E3, 1.0, 1.0, 0.3 ) ) );
  858.     Cbsp3 = cbspline( 4,
  859.                       list( ctlpt( E3, 0.1,  0.1, 0.1 ),
  860.                             ctlpt( E3, 0.25, 0.0, -1.0 ),
  861.                             ctlpt( E3, 0.5,  0.0, 2.0 ),
  862.                             ctlpt( E3, 0.75, 0.0, -1.0 ),
  863.                             ctlpt( E3, 1.0,  0.2, 0.2 ) ),
  864.                       list( KV_OPEN ) );
  865.     Cbsp4 = cbspline( 4,
  866.                       list( ctlpt( E3, 0.4,  1.0, 0.4 ),
  867.                             ctlpt( E3, 0.25, 1.0, 1.0 ),
  868.                             ctlpt( E3, 0.5,  1.0, -2.0 ),
  869.                             ctlpt( E3, 0.75, 1.0, 1.0 ),
  870.                             ctlpt( E3, 1.0,  1.0, 0.3 ) ),
  871.                       list( KV_OPEN ) );
  872.     Srf = BOOLSUM( Cbzr1, Cbzr2, Cbsp3, Cbsp4 );
  873.  
  874.                                      BOX
  875.                                      ---
  876.  
  877.  PolygonType BOX( VectorType Point,
  878.                   NumericType Dx, NumericType Dy, NumericType Dz )
  879.  
  880.    Creates a BOX polygonal object, whose boundary is coplanar with the
  881.  XY, XZ, and YZ planes. The BOX is defined by Point as
  882.  base position, and Dx, Dy, Dz as BOX dimensions. Negative dimensions
  883.  are allowed.
  884.  
  885.  Example:
  886.  
  887.     B = BOX( vector( 0, 0, 0 ), 1, 1, 1);
  888.  
  889.  creates a unit cube from 0 to 1 in all axes.
  890.  
  891.                                    BZR2BSP
  892.                                    -------
  893.  
  894.  CurveType BZR2BSP( CurveType Crv )
  895.  
  896.  or
  897.  
  898.  SurfaceType BZR2BSP( SurfaceType Srf )
  899.  
  900.    Creates a Bspline curve or a Bspline surface from the given Bezier curve or
  901.  Bezier surface. The Bspline curve or surface is assigned open end knot
  902.  vector(s) with no interior knots, in the parametric domain of zero to one.
  903.  
  904.  Example:
  905.  
  906.     BspSrf = BZR2BSP( BzrSrf );
  907.  
  908.                                    BSP2BZR
  909.                                    -------
  910.  
  911.  CurveType | ListType BSP2BZR( CurveType Crv )
  912.  
  913.  or
  914.  
  915.  SurfaceType | ListType BSP2BZR( SurfaceType Srf )
  916.  
  917.    Creates Bezier curve(s) or surface(s) from a given Bspline curve or a
  918.  Bspline surface. The Bspline input is subdivided at all internal knots to
  919.  create Bezier curves or surfaces. Therefore, if the input Bspline does have
  920.  internal knots, a list of Bezier curves or surfaces is returned. Otherwise,
  921.  a single Bezier curve or surface is returned.
  922.  
  923.  Example:
  924.  
  925.     BzrCirc = BSP2BZR( circle( vector( 0.0, 0.0, 0.0 ), 1.0 ) );
  926.  
  927.  would subdivide the unit circle into four 90 degrees Bezier arcs returned
  928.  in a list.
  929.  
  930.                                    CBEZIER
  931.                                    -------
  932.  
  933.  CurveType CBEZIER( ListType CtlPtList )
  934.  
  935.    Creates a Bezier curve out of the provided control point list. CtlPtList
  936.  is a list of control points, all of which must be of the same type (E1-E5, P1-P5),
  937.  defining the curve's control polygon.
  938.  
  939.  Example:
  940.  
  941.     s45 = sin(pi / 4);
  942.     Arc90 = CBEZIER( list( ctlpt( P2, 1.0, 0.0, 1.0 ),
  943.                            ctlpt( P2, s45, s45, s45 ),
  944.                            ctlpt( P2, 1.0, 1.0, 0.0 ) ) );
  945.  
  946.  constructs an arc of 90 degrees as a rational quadratic Bezier curve.
  947.  
  948.                                   CBSPLINE
  949.                                   --------
  950.  
  951.  CurveType CBSPLINE( NumericType Order, ListType CtlPtList,
  952.                                                         ListType KnotVector )
  953.  
  954.    Creates a Bspline curve out of the provided control point list, the
  955.  knot vector, and the specified order. CtlPtList is a list of control
  956.  points, all of which must be of the same type (E1-E5, P1-P5), defining the
  957.  curve's control polygon. The length of the KnotVector must be equal
  958.  to the number of control points in CtlPtList plus the Order.
  959.    The knot vector list may be specified as either list( KV_OPEN ) or
  960.  list( KV_FLOAT ) in which a uniform open or uniform floating knot
  961.  vector with the appropriate length is automatically constructed. 
  962.  
  963.  Example:
  964.  
  965.     s45 = sin(pi / 4);
  966.     HalfCirc = CBSPLINE( 3,
  967.                       list( ctlpt( P3, 1.0,  0.0, 0.0,  1.0 ),
  968.                             ctlpt( P3, s45, -s45, 0.0,  s45 ),
  969.                             ctlpt( P3, 1.0, -1.0, 0.0,  0.0 ),
  970.                             ctlpt( P3, s45, -s45, 0.0, -s45 ),
  971.                             ctlpt( P3, 1.0,  0.0, 0.0, -1.0 ) ),
  972.                       list( 0, 0, 0, 1, 1, 2, 2, 2 ) );
  973.  
  974.  constructs an arc of 180 degrees in the XZ plane as a rational quadratic
  975.  Bspline curve.
  976.  
  977.                                    CCINTER
  978.                                    -------
  979.  
  980.  ListType CCINTER( CurveType Crv1, CurveType Crv2, NumericType Epsilon,
  981.                                                        NumericType SelfInter )
  982.  
  983.  or
  984.  
  985.  SurfaceType CCINTER( CurveType Crv1, CurveType Crv2, NumericType Epsilon,
  986.                                                        NumericType SelfInter )
  987.  
  988.    Computes the intersection point(s) of Crv1 and Crv2 in the
  989.  XY plane. Since this computation involves numeric operations, Epsilon
  990.  controls the accuracy of the parametric values of the result.
  991.    It returns a list of PointTypes, each containing the parameter of Crv1
  992.  in the X coordinate, and the parameter of Crv2 in the Y coordinate.
  993.    If, however, Epsilon is negative, a scalar field surface representing
  994.  the square of the distance function is returned instead.
  995.    If SelfInter is TRUE, Crv1 and Crv2 can be the same
  996.  curve, and self-intersection points are searched instead.
  997.  
  998.  Example:
  999.  
  1000.  crv1 = cbspline( 3,
  1001.                   list( ctlpt( E2, 0, 0 ),
  1002.                         ctlpt( E2, 0.0.5 ),
  1003.                         ctlpt( E2, 0.5, 0.7 ),
  1004.                         ctlpt( E2, 1, 1 ) ),
  1005.                   list( KV_OPEN ) );
  1006.  crv2 = cbspline( 3,
  1007.                   list( ctlpt( E2, 1, 0 ),
  1008.                         ctlpt( E2, 0.7, 0.25 ),
  1009.                         ctlpt( E2, 0.3, 0.5 ),
  1010.                         ctlpt( E2, 0, 1 ) ),
  1011.                   list( KV_OPEN ) );
  1012.  inter_pts = CCINTER( crv1, crv2, 0.0001, FALSE );
  1013.  
  1014.  Computes the parameter values of the intersection point of crv1 and
  1015.  crv2 to a tolerance of 0.0001.
  1016.  
  1017.                                    CCRVTR
  1018.                                    ------
  1019.  
  1020.  NumericType CCRVTR( CurveType Crv, NumericType Epsilon )
  1021.  
  1022.  or
  1023.  
  1024.  CurveType CCRVTR( CurveType Crv, NumericType Epsilon )
  1025.  
  1026.    Computes the extreme curvature points on Crv in the XY plane.
  1027.  This set includes not only points of maximum (convexity) and mimumum
  1028.  (concavity) curvature, but also points of zero curvature such as
  1029.  inflection points.
  1030.    Since this operation is partially numeric, Epsilon is used to set
  1031.  the needed accuracy. It returns the parameter value(s) of the location(s)
  1032.  with extreme curvature along the Crv.
  1033.    If, however, Epsilon is negative, the curvature scalar field
  1034.  curve is returned as a two dimensional rational vector field curve, for
  1035.  which the first dimension is equal to the parameter, and the second is the
  1036.  curvature value at that parameter.
  1037.  
  1038.     This function computes the curvature scalar field for planar curves as,
  1039.  --------------------------------------------------------------------------
  1040.                                       
  1041.                                       
  1042.                                    x' y'' - x'' y' 
  1043.                          --------------------------
  1044.                             k(t) = ----------------
  1045.                          --------------------------
  1046.                                         2     2  3/2
  1047.                          ---------------------------
  1048.                                      ( x'  + y'  )
  1049.                           ------------------------
  1050.                                       
  1051.                                       
  1052.  and computes kN for three dimensional curves as the following vector field,
  1053. ----------------------------------------------------------------------------
  1054.                                       
  1055.                                       
  1056.                                       C' x C''     C'    (C' x C'') x C'
  1057.     --------------------------------------------------------------------
  1058.        k(t) N(t) = K(t) B(t) x T(t) = -------- x ----- = ---------------
  1059.     --------------------------------------------------------------------
  1060.                                               3    | C' |            4
  1061.       ----------------------------------------------------------------
  1062.                                           | C'|                 | C' |
  1063.        ---------------------------------------------------------------
  1064.  
  1065.  The extremum values are extracted from the computed curvature field.
  1066.  This curvature field is a high order curve, even if the input geometry is
  1067.  of low order. This is especially true for rational curves, for which the
  1068.  quotient rule for differentiation is used and almost doubles the degree
  1069.  in every differentiation.
  1070.  
  1071.  See also CZEROS, CEXTREMES, and CCRVTR.
  1072.  
  1073.  Example:
  1074.  
  1075.  crv = cbezier( list( ctlpt( E2, -1.0,  1.0 ),
  1076.                       ctlpt( E2, -0.5, -2.0 ),
  1077.                       ctlpt( E2,  0.0,  2.0 ),
  1078.                       ctlpt( E2,  1.0, -1.0 ) ) );
  1079.  
  1080.  crvtr = ccrvtr( crv, 0.001 );
  1081.  pt_crvtr = nil();
  1082.  pt = nil();
  1083.  for ( i = 1, 1, listsize( crvtr ),
  1084.      pt = ceval( crv, nth( crvtr, i ) ) ):
  1085.      snoc( pt, pt_crvtr )
  1086.  );
  1087.  interact( list( crv, pt_crvtr ) );
  1088.  
  1089.  finds the extreme curvature points in Crv and displays them all
  1090.  with the curve.
  1091.  
  1092.                                    CDERIVE
  1093.                                    -------
  1094.  
  1095.  CurveType CDERIVE( CurveType Curve )
  1096.  
  1097.    Returns a vector field curve representing the differentiated curve,
  1098.  also known as the Hodograph curve.
  1099.  
  1100.  Example:
  1101.  
  1102.  Hodograph = CDERIVE( Crv );
  1103.  
  1104.                                    CDIVIDE
  1105.                                    -------
  1106.  
  1107.  ListType CDIVIDE( CurveType Curve, NumericType Param )
  1108.  
  1109.    Subdivides a curve into two sub-curves at the specified parameter value.
  1110.  Curve can be either a Bspline curve in which Param must be
  1111.  within the Curve's parametric domain, or a Bezier curve in which Param
  1112.  must be in the range of zero to one.
  1113.  
  1114.    It returns a list of the two sub-curves. The individual curves may be
  1115.  extracted from the list using the NTH command.
  1116.  
  1117.  Example:
  1118.  
  1119.  CrvLst = CDIVIDE( Crv, 0.5 );
  1120.  Crv1 = nth( CrvLst, 1 );
  1121.  Crv2 = nth( CrvLst, 2 );
  1122.  
  1123.  subdivides the curve Crv at the parameter value of 0.5.
  1124.  
  1125.                                    CEDITPT
  1126.                                    -------
  1127.  
  1128.  CurveType CEDITPT( CurveType Curve, CtlPtType CtlPt, NumericType Index )
  1129.  
  1130.    Provides a simple mechanism to manually modify a single control point number
  1131.  Index (base count is 0) in Curve, by substituting CtlPt
  1132.  instead. CtlPt must have the same point type as the control points of
  1133.  the  Curve. Original curve Curve is not modified.
  1134.  
  1135.  Example:
  1136.  
  1137.     CPt = ctlpt( E3, 1, 2, 3 );
  1138.     NewCrv = CEDITPT( Curve, CPt, 1 );
  1139.  
  1140.  constructs a NewCrv with the second control point of Curve being
  1141.  CPt.
  1142.  
  1143.                                     CEVAL
  1144.                                     -----
  1145.  
  1146.  CtlPtType CEVAL( CurveType Curve, NumericType Param )
  1147.  
  1148.    Evaluates the provided Curve at the given Param value.
  1149.  Param should be in the curve's parametric domain if Curve is
  1150.  a Bspline curve, or between zero and one if Curve is a Bezier curve.
  1151.  The returned control point has the same point type as the control points
  1152.  of the Curve.
  1153.  
  1154.  Example:
  1155.  
  1156.     CPt = CEVAL( Crv, 0.25 );
  1157.  
  1158.  evaluates Crv at the parameter value of 0.25.
  1159.  
  1160.                                   CEXTREMES
  1161.                                   ---------
  1162.  
  1163.  ListType CEXTREMES( CurveType Crv, NumericType Epsilon, NumericType Axis )
  1164.  
  1165.    Computes the extreme set of the given Crv in the given axis (1 for X,
  1166.  2 for Y, 3 for Z). Since this computation is numeric, an Epsilon is
  1167.  also required to specify the desired tolerance. It returns a list of
  1168.  all the parameter values (NumericType) in which the curve takes an extreme
  1169.  value.
  1170.  
  1171.  Example:
  1172.  
  1173.     extremes = cextremes( crv, 0.0001, 1 );
  1174.  
  1175.  Computes the extreme set of curve crv, in the X axis, with
  1176.  error tolerance of 0.0001. See also CZERO.
  1177.  
  1178.                                   CINFLECT
  1179.                                   --------
  1180.  
  1181.  ListType CINFLECT( CurveType Crv, NumericType Epsilon )
  1182.  
  1183.  or
  1184.  
  1185.  CurveType CINFLECT( CurveType Crv, NumericType Epsilon )
  1186.  
  1187.    Computes the inflection points of Crv in the XY plane.
  1188.  Since this computation is numeric, an Epsilon is also required
  1189.  to specify the desired tolerance. It returns a list of all the
  1190.  parameter values (NumericType) in which the curve has an inflection point.
  1191.    If, however, Epsilon is negative, a scalar field curve representing
  1192.  the sign of the curvature of the curve is returned instead.
  1193.  
  1194.                 The sign of curvature scalar field is equal to
  1195.                -----------------------------------------------
  1196.                                       
  1197.                                       
  1198.                               s(t) = x' y'' - x'' y' 
  1199.                        ------------------------------
  1200.                                       
  1201.                                       
  1202.  Example:
  1203.  
  1204.     inflect = CINFLECT( crv, 0.001 );
  1205.     pt_inflect = nil();
  1206.     pt = nil();
  1207.     for ( i = 1, 1, listsize( inflect ),
  1208.             pt = ceval( crv, nth( inflect, i ) ):
  1209.             snoc( pt, pt_inflect )
  1210.         );
  1211.     interact( list( axes, crv, pt_inflect ), 0);
  1212.  
  1213.  Computes the set of inflection points of curve crv with error
  1214.  tolerance of 0.001. This set is then scanned in a loop and
  1215.  evaluated to the curve's locations which are then displayed with the crv.
  1216.  See also CZEROS, CEXTREMES, and CCRVTR.
  1217.  
  1218.                                    CIRCLE
  1219.                                    ------
  1220.  
  1221.  CurveType CIRCLE( VectorType Center, NumericType Radius )
  1222.  
  1223.    Constructs a circle at the specified Center with the specified
  1224.  Radius. The returned circle is a Bspline curve of four piecewise Bezier
  1225.  90 degree arcs. The construced circle is always parallel to the XY plane.
  1226.  Use the linear transformation routines to place the circle in the appropriate
  1227.  orientation and location.
  1228.  
  1229.                                   CIRCPOLY
  1230.                                   --------
  1231.  
  1232.  PolygonType CIRCPOLY( VectorType Normal, VectorType Trans, NumericType Radius )
  1233.  
  1234.    Defines a circular polygon in a plane perpendicular to Normal that
  1235.  contains the Trans point. Constructed polygon is centered at
  1236.  Trans. RESOLUTION vertices will be defined with Radius from
  1237.  distance from Trans.
  1238.  
  1239.    Alternative ways to construct a polygon are manual construction of the
  1240.  vertices using POLY, or the construction of a flat ruled surface using
  1241.  RULEDSRF.
  1242.  
  1243.                                     CMESH
  1244.                                     -----
  1245.  
  1246.  CurveType CMESH( SurfaceType Srf, ConstantType Direction, NumericType Index )
  1247.  
  1248.    Returns a single ROW or COLumn as specified by the Direction and
  1249.  Index (base count is 0) of the control mesh of surface Srf.
  1250.  
  1251.    The returned curve will have the same knot vector as Srf in the
  1252.  appropriate direction. See also CSURFACE.
  1253.  
  1254.    This curve is not necessarily in the surface Srf.
  1255.  
  1256.  Example:
  1257.  
  1258.     Crv = CMESH( Srf, COL, 0 );
  1259.  
  1260.  extracts the first column of surface Srf as a curve. See also
  1261.  
  1262.                                    COERCE
  1263.                                    ------
  1264.  
  1265.  AnyType COERCE( AnyType Object, ConstantType NewType )
  1266.  
  1267.    Provides a coercion mechanism between different objects or object types.
  1268.  PointType, VectorType, PlaneType, CtlPtType can be all coerced to each
  1269.  other by using the NewType of POINT_TYPE, VECTOR_TYPE, PLANE_TYPE,
  1270.  or one of E1-E5, P1-P5 (CtlPtType). Similarly, CurveType and SurfaceType
  1271.  can be coerced to hold different CtlPtType of control points.
  1272.  
  1273.  Example:
  1274.  
  1275.     CrvE2 = COERCE( Crv, E2 );
  1276.  
  1277.  coerce Crv to a new curve that will have an E2 CtlPtType control
  1278.  points. Coerction of a projective curve (P1-P5) to a Euclidean curve
  1279.  (E1-E5) does not preseve the shape of the curve.
  1280.  
  1281.                                    COMPOSE
  1282.                                    -------
  1283.  
  1284.  CurveType COMPOSE( CurveType Crv1, CurveType Crv2 )
  1285.  
  1286.  or
  1287.  
  1288.  CurveType COMPOSE( SurfaceType Srf, CurveType Crv )
  1289.  
  1290.    Symbolically compute the composition curve Crv1(Crv2(t)) or
  1291.  Srf(Crv(t)). In Crv1(Crv2(t), Crv1 can be any curve
  1292.  while Crv2 must be a one-dimensional curve that is either E1 or
  1293.  P1. In Srf(Crv(t)), Srf can be any surface, while Crv
  1294.  must be a two-dimensional curve, that is either E2 or P2. Both Crv2
  1295.  in the curve's composition, and Crv is the surface's composition
  1296.  must be contained in the curve or surface parametric domain.
  1297.  
  1298.  Example:
  1299.  
  1300.    srf = sbezier( list( list( ctlpt( E3, 0.0, 0.0, 0.0 ),
  1301.                               ctlpt( E3, 0.0, 0.5, 1.0 ),
  1302.                               ctlpt( E3, 0.0, 1.0, 0.0 ) ),
  1303.                         list( ctlpt( E3, 0.5, 0.0, 1.0 ),
  1304.                               ctlpt( E3, 0.5, 0.5, 0.0 ),
  1305.                               ctlpt( E3, 0.5, 1.0, 1.0 ) ),
  1306.                         list( ctlpt( E3, 1.0, 0.0, 1.0 ),
  1307.                               ctlpt( E3, 1.0, 0.5, 0.0 ),
  1308.                               ctlpt( E3, 1.0, 1.0, 1.0 ) ) ) );
  1309.    crv = coerce( circle( vector( 0.0, 0.0, 1.0 ), 0.4 ), p2 ) *
  1310.          trans( vector( 0.5, 0.5, 0.0 ) );
  1311.    comp_crv = COMPOSE( srf, crv );
  1312.  
  1313.  compose a circle Crv to be on the surface Srf.
  1314.  
  1315.                                     CON2
  1316.                                     ----
  1317.  
  1318.  PolygonType CON2( VectorType Center, VectorType Direction,
  1319.                    NumericType Radius1, NumericType Radius2 )
  1320.  
  1321.    Creates a truncated CONE geometric object, defined by Center as the
  1322.  center of the main base of the CONE, Direction as both the CONE's axis
  1323.  and the length of CONE, and the two radii Radius1/2 of the two bases of
  1324.  the CONE.
  1325.  
  1326.    Unlike the regular cone (CONE) constructor which has inherited
  1327.  discontinuities in its generated normals at the apex, CON2 can be used to
  1328.  form a (truncated) cone with continuous normals. 
  1329.    See RESOLUTION for the accuracy of the CON2 approximation as a polygonal
  1330.  model.
  1331.  
  1332.  Example:
  1333.  
  1334.     Cone2 = CON2( vector( 0, 0, -1 ), vector( 0, 0, 4 ), 2, 1 );
  1335.  
  1336.  constructs a truncated cone with bases parallel to the XY plane at
  1337.  Z = -1 and Z = 3, and with radii of 2 and 1 respectively.
  1338.  
  1339.                                     CONE
  1340.                                     ----
  1341.  
  1342.  PolygonType CONE( VectorType Center, VectorType Direction,
  1343.                    NumericType Radius )
  1344.  
  1345.    Creates a CONE geometric object, defined by Center as the center of
  1346.  the base of the CONE, Direction as the CONE's axis and height, and
  1347.  Radius as the radius of the base of the CONE.
  1348.    See RESOLUTION for accuracy of the CONE approximation as a polygonal model. 
  1349.  
  1350.  Example:
  1351.  
  1352.     Cone1 = CONE( vector( 0, 0, 0 ), vector( 1, 1, 1 ), 1 );
  1353.  
  1354.  constructs a cone based in an XY parallel plane, centered at the origin
  1355.  with radius 1 and with tilted apex at ( 1, 1, 1 ).
  1356.  
  1357.    See also CON2.
  1358.  
  1359.                                    CONVEX
  1360.                                    ------
  1361.  
  1362.  PolygonType CONVEX( PolygonType Object )
  1363.  
  1364.    Converts non-convex polygons in Object, into convex ones. New vertices
  1365.  are introduced into the polygonal data during this process. The Boolean
  1366.  operations require the input to have convex polygons only (although it may
  1367.  return non convex polygons...) and it automatically converts non-convex input
  1368.  polygons to convex ones, using this same routine.
  1369.  
  1370.    However, some external tools (like irit2ray, poly3d-r and poly3d-h) require
  1371.  convex polygons. This function must be used on the objects to guarantee that
  1372.  only convex polygons are saved into data files for these external tools.
  1373.  
  1374.     CnvxObj = CONVEX( Obj );
  1375.     save( "data", CnvxObj );
  1376.  
  1377.  converts non-convex polygons into convex ones, so that the data file can be
  1378.  used by external tools requiring convex polygons.
  1379.  
  1380.                                     COORD
  1381.                                     -----
  1382.  
  1383.  AnyType COORD( AnyType Object, NumericType Index )
  1384.  
  1385.    Extracts an element from a given Object, at index Index. From
  1386.  a PointType, VectorType, PlaneType, CtlPtType and MatrixType, a NumericType
  1387.  is returned with Index 0 for the X axis, 1 for the Y axis etc.
  1388.  Index 0 denotes the weight of CtlPtType. For a PolygonType that
  1389.  contains more than one polygon, the Indexth polygon is returned. For
  1390.  a PolygonType that contains a single Polygon, the Indexth vertex is
  1391.  returned. For a CurveType or a SurfaceType, the Indexth CtlPtType is
  1392.  returned. For a ListType, COORD behaves like NTH and returns the Indexth
  1393.  object in the list.
  1394.  
  1395.  Example:
  1396.  
  1397.     a = vector( 1, 2, 3 );
  1398.     vector( COORD( a, 0 ), COORD( a, 1 ), COORD( a, 2 ) );
  1399.  
  1400.     a = ctlpt( P2, 6, 7, 8, 9 );
  1401.     ctlpt( P3, coord( a, 0 ), coord( a, 1 ), coord( a, 2 ), coord( a, 3 ) );
  1402.  
  1403.     a = plane( 10, 11, 12, 13 );
  1404.     plane( COORD( a, 0 ), COORD( a, 1 ), COORD( a, 2 ), COORD( a, 3 ) );
  1405.  
  1406.  constructs a vector/ctlpt/plane and reconstructs it by extracting the
  1407.  constructed scalar components of the objects using COORD.
  1408.  
  1409.    See also COERCE.
  1410.  
  1411.                                    CRAISE
  1412.                                    ------
  1413.  
  1414.  CurveType CRAISE( CurveType Curve, NumericType NewOrder )
  1415.  
  1416.    Raise Curve to the NewOrder Order specified.
  1417.  
  1418.  Example:
  1419.  
  1420.     Crv = ctlpt( E3, 0.0, 0.0, 0.0 ) +
  1421.           ctlpt( E3, 0.0, 0.0, 1.0 ) +
  1422.           ctlpt( E3, 1.0, 0.0, 1.0 );
  1423.     Crv2 = CRAISE( Crv, 4 );
  1424.  
  1425.  raises the 90 degrees corner linear Bspline curve Crv to be a cubic.
  1426.  
  1427.                                    CREFINE
  1428.                                    -------
  1429.  
  1430.  CurveType CREFINE( CurveType Curve, NumericType Replace, ListType KnotList )
  1431.  
  1432.    Provides the ability to Replace a knot vector of Curve, or refine 
  1433.  it. KnotList is a list of knots to refine Curve at. All knots
  1434.  should be contained in the parametric domain of the Curve. If the knot
  1435.  vector is replaced, the length of KnotList should be identical to the
  1436.  length of the original knot vector of the Curve. If Curve is a
  1437.  Bezier curve, it is automatically promoted to be a Bspline curve.
  1438.  
  1439.  Example:
  1440.  
  1441.     Crv2 = CREFINE( Crv, FALSE, list( 0.25, 0.5, 0.75 ) );
  1442.  
  1443.  refines Crv and adds three new knots at 0.25, 0.5, and 0.75.
  1444.  
  1445.                                    CREGION
  1446.                                    -------
  1447.  
  1448.  CurveType CREGION( CurveType Curve, NumericType MinParam,
  1449.                                                        NumericType MaxParam )
  1450.  
  1451.    Extracts a region from Curve between MinParam and MaxParam.
  1452.  Both MinParam and MaxParam should be contained in the
  1453.  parametric domain of the Curve.
  1454.  
  1455.  Example:
  1456.  
  1457.     SubCrv = CREGION( Crv, 0.3, 0.6 );
  1458.  
  1459.  extracts the region from Crv from the parameter value 0.3 to the
  1460.  parameter value 0.6.
  1461.  
  1462.                                    CROSSEC
  1463.                                    -------
  1464.  
  1465.  PolygonType CROSSEC( PolygonType Object )
  1466.  
  1467.    This feature is NOT implemented.
  1468.  
  1469.                                   CRVLNDST
  1470.                                   --------
  1471.  
  1472.  NumericType CRVLNDST( CurveType Crv, PointType PtOnLine, VectorType LnDir,
  1473.                                  NumericType IsMinDist, NumericType Epsilon )
  1474.  
  1475.  or
  1476.  
  1477.  ListType CRVLNDST( CurveType Crv, PointType PtOnLine, VectorType LnDir,
  1478.                                 NumericType IsMinDist, NumericType Epsilon )
  1479.  
  1480.    Computes the closest (if IsMinDist is TRUE, farthest if FALSE) point
  1481.  on Curve to the line specified by PtOnLine and LnDir as a
  1482.  point on the line and a line direction.
  1483.    Since this operation is partially numeric, Epsilon is used to set
  1484.  the needed accuracy. It returns the parameter value of the location on
  1485.  Crv closest to the line.
  1486.    If, however, Epsilon is negative, -Epsilon is used instead,
  1487.  and all local extrema in the distance function are returned as a list
  1488.  (both minima and maxima).
  1489.    If the line and the curve intersect, the point of intersection is
  1490.  returned as the minimum.
  1491.  
  1492.  Example:
  1493.  
  1494.     Param = CRVLNDST( Crv, linePt, lineVec, TRUE, 0.001 );
  1495.  
  1496.  finds the closest point on Crv to the line defined by linePt
  1497.  and lineVec.
  1498.  
  1499.                                   CRVPTDST
  1500.                                   --------
  1501.  
  1502.  NumericType CRVPTDST( CurveType Crv, PointType Point, NumericType IsMinDist,
  1503.                                                          NumericType Epsilon )
  1504.  
  1505.  or
  1506.  
  1507.  ListType CRVPTDST( CurveType Crv, PointType Point, NumericType IsMinDist,
  1508.                                                          NumericType Epsilon )
  1509.  
  1510.    Computes the closest (if IsMinDist is TRUE, farthest if FALSE) point
  1511.  on Crv to Point.
  1512.    Since this operation is partially numeric, Epsilon is used to set
  1513.  the needed accuracy. It returns the parameter value of the location on
  1514.  Crv closest to Point.
  1515.    If, however, Epsilon is negative, -Epsilon is used instead,
  1516.  and all local extrema in the distance function are returned as a list
  1517.  (both minima and maxima).
  1518.  
  1519.  Example:
  1520.  
  1521.     Param = CRVPTDST( Crv, Pt, FALSE, 0.0001 ); 
  1522.  
  1523.  finds the farthest point on Crv from point Pt.
  1524.  
  1525.                                   CSURFACE
  1526.                                   --------
  1527.  
  1528.  CurveType CSURFACE( SurfaceType Srf, ConstantType Direction,
  1529.                                                           NumericType Param )
  1530.  
  1531.    Extract an isoparametric curve out of Srf in the specified
  1532.  Direction (ROW or COL) at the specified parameter value Param.
  1533.  Param must be contained in the parametric domain of Srf in
  1534.  Direction direction.
  1535.  The returned curve is in the surface Srf.
  1536.  
  1537.  Example:
  1538.  
  1539.     Crv = CSURFACE( Srf, COL, 0.15 ); 
  1540.  
  1541.  extracts an isoparametric curve in the COLumn direction at the parameter
  1542.  value of 0.15 from surface Srf. See also CMESH, COMPOSE.
  1543.  
  1544.                                   CTANGENT
  1545.                                   --------
  1546.  
  1547.  VectorType CTANGENT( CurveType Curve, NumericType Param )
  1548.  
  1549.    Computes the tangent vector to Curve at the parameter value Param.
  1550.    The returned vector has a unit length.
  1551.  
  1552.  Example:
  1553.  
  1554.     Tang = CTANGENT( Crv, 0.5 );
  1555.  
  1556.  computes the tangent vector to Crv at the parameter value of 0.5.
  1557.  
  1558.                                     CTLPT
  1559.                                     -----
  1560.  
  1561.  CPt = CTLPT( ConstantType PtType, NumericType Coord1, ... )
  1562.  
  1563.    Constructs a single control point to be used in the construction of curves
  1564.  and surfaces. Points can have from one to five dimensions, and may be
  1565.  either Euclidean or Projective (rational). Points' type is set via the
  1566.  constants E1 to E5 and P1 to P5. The coordinates of the point are specified
  1567.  in order, weight is first if rational.
  1568.  
  1569.  Examples:
  1570.  
  1571.     CPt1 = CTLPT( E3, 0.0, 0.0, 0.0 );
  1572.     CPt2 = CTLPT( P2, 0.707, 1.414, 1.414 );
  1573.  
  1574.  constructs an E3 point at the origin and a P2 rational point with
  1575.  a weight of 0.707.
  1576.  
  1577.                                     CYLIN
  1578.                                     -----
  1579.  
  1580.  PolylineType CYLIN( VectorType Center, VectorType Direction,
  1581.                      NumericType Radius )
  1582.  
  1583.    Creates a CYLINder geometric object, defined by Center as center of
  1584.  the base of the CYLINder, Direction as the CYLINder's axis and height,
  1585.  and Radius as the radius of the base of the CYLINder.
  1586.    See RESOLUTION for the accuracy of the CYLINder approximation as a
  1587.  polygonal model.
  1588.  
  1589.  Example:
  1590.  
  1591.     Cylinder1 = CYLIN( vector( 0, 0, 0 ), vector( 1, 0, 0 ), 10 );
  1592.  
  1593.  constructs a cylinder along the X axis from the origin to X = 10.
  1594.  
  1595.                                    CZEROS
  1596.                                    ------
  1597.  
  1598.  ListType CZEROS( CurveType Crv, NumericType Epsilon, NumericType Axis )
  1599.  
  1600.    Computes the zero set of the given Crv in the given axis (1 for X,
  1601.  2 for Y, 3 for Z). Since this computation is numeric, an Epsilon is
  1602.  also required to specify the desired tolerance. It returns a list of
  1603.  all the parameter values (NumericType) the curve is zero.
  1604.  
  1605.  Example:
  1606.  
  1607.     xzeros = CZEROS( cb, 0.001, 1 );
  1608.     pt_xzeros = nil();
  1609.     pt = nil();
  1610.     for ( i = 1, 1, listsize( xzeros ),
  1611.             pt = ceval( cb, nth( xzeros, i ) ):
  1612.             snoc( pt, pt_xzeros )
  1613.         );
  1614.     interact( list( axes, cb, pt_xzeros ), 0);
  1615.  
  1616.  Computes the X zero set of curve cb with error tolerance
  1617.  of 0.001. This set is then scanned in a loop and evaluated to
  1618.  the curve's locations, which are then displayed.
  1619.  See also CINFLECT.
  1620.  
  1621.                                    EXTRUDE
  1622.                                    -------
  1623.  
  1624.  PolygonType EXTRUDE( PolygonType Object, VectorType Dir )
  1625.  
  1626.  or
  1627.  
  1628.  SurfaceType EXTRUDE( CurveType Object, VectorType Dir )
  1629.  
  1630.    Creates an extrusion of the given Object. If Object is a
  1631.  PolygonObject, its first polygon is used as the base for the extrusion in
  1632.  Dir direction, and a closed PolygonObject is constructed. If Object
  1633.  is a CurveType, an extrusion surface is constructed instead, which is not
  1634.  a closed object (the two bases of the extrusion are excluded, and the curve
  1635.  may be open by itself).
  1636.  
  1637.    Direction Dir cannot be coplanar with the polygon plane. The curve
  1638.  may be nonplanar.
  1639.  
  1640.  Example:
  1641.  
  1642.     Cross = cbspline( 3,
  1643.                       list( ctlpt( E2, -0.018, 0.001 ),
  1644.                             ctlpt( E2,  0.018, 0.001 ),
  1645.                             ctlpt( E2,  0.019, 0.002 ),
  1646.                             ctlpt( E2,  0.018, 0.004 ),
  1647.                             ctlpt( E2, -0.018, 0.004 ),
  1648.                             ctlpt( E2, -0.019, 0.001 ) ),
  1649.                       list( KV_OPEN ) );
  1650.     Cross = Cross + -Cross * scale( vector( 1, -1, 1 ) );
  1651.     Napkin = EXTRUDE( Cross * scale( vector( 1.6, 1.6, 1.6 ) ),
  1652.                       vector( 0.02, 0.03, 0.2 ) );
  1653.  
  1654.  constructs a closed cross section Cross by duplicating one half of
  1655.  it in reverse and merging the two sub-curves. Cross is then used as
  1656.  the cross-section for the extrusion operation.
  1657.  
  1658.                                   FFCOMPAT
  1659.                                   --------
  1660.  
  1661.  FFCOMAPT( CurveType Crv1, CurveType Crv2 )
  1662.  
  1663.  or
  1664.  
  1665.  FFCOMAPT( SurfaceType Srf1, SurfaceType Srf2 )
  1666.  
  1667.  Makes the given two curves or surfaces compatible by making them share the
  1668.  same point type, same curve type, same degree, and the same continuity.
  1669.  Same point type is gained by promoting a lower dimension into a higher one,
  1670.  and non-rational to rational points. Bezier curves are promoted to Bspline
  1671.  curves if necessary, for curve type compatibility. Degree compatibility is
  1672.  achieved by raising the degree of the lower order curve. Continuity is
  1673.  achieve by refining both curves to the space with the same (unioned) knot
  1674.  vector. This function returns nothing and compatibility is made
  1675.  in place.
  1676.  
  1677.  Example:
  1678.  
  1679.  FFCOMPAT( Srf1, Srf2 );
  1680.  
  1681.  See also SMORPH.
  1682.  
  1683.                                     GBOX
  1684.                                     ----
  1685.  
  1686.  PolygonType GBOX( VectorType Point,
  1687.                    VectorType Dx, VectorType Dy, VectorType Dz )
  1688.  
  1689.    Creates a parallelepiped - Generalized BOX polygonal object, defined by
  1690.  Point as base position, and Dx, Dy, Dz as 3 3D vectors to define
  1691.  the 6 faces of this generalized BOX. The regular BOX object is a special case
  1692.  of GBOX where Dx = vector(Dx, 0, 0), Dy = vector(0, Dy, 0), and
  1693.  Dz = vector(0, 0, Dz).
  1694.  
  1695.    Dx, Dy, Dz must all be independent in order to create an
  1696.  object with positive volume.
  1697.  
  1698.  Example:
  1699.  
  1700.     GB = GBOX(vector(0.0, -0.35, 0.63), vector(0.5, 0.0, 0.5),
  1701.                                         vector(-0.5, 0.0, 0.5),
  1702.                                         vector(0.0, 0.7, 0.0));
  1703.  
  1704.                                   GPOLYGON
  1705.                                   --------
  1706.  
  1707.  PolygonType GPOLYGON( GeometryTreeType Object )
  1708.  
  1709.    Approximates all Surface(s) in Object with polygons using the
  1710.  RESOLUTION and FLAT4PLY variables. The larger the RESOLUTION is, the finer
  1711.  (more polygons) the resulting approximation will be.
  1712.  
  1713.    FLAT4PLY is a Boolean flag controlling the conversion of an (almost) flat
  1714.  patch into four (TRUE) or two (FALSE) polygons. Normals are computed to
  1715.  polygon vertices using surface normals, so Gouraud or Phong shading can be
  1716.  exploited. It returns a single polygonal object.
  1717.  
  1718.  Example:
  1719.  
  1720.     Polys = GPOLYGON( list( Srf1, Srf2, Srf3 ) );
  1721.  
  1722.  Converts to polygons the three surfaces Srf1, Srf2, and Srf3.
  1723.  
  1724.                                   GPOLYLINE
  1725.                                   ---------
  1726.  
  1727.  PolylineType GPOLYLINE( GeometryTreeType Object )
  1728.  
  1729.    Converts all Surface(s) and Curves(s) in Object into polylines using
  1730.  the RESOLUTION variable. The larger the RESOLUTION is, the finer the resulting
  1731.  approximation will be. It returns a single polyline object.
  1732.  
  1733.  Example:
  1734.  
  1735.     Polys = GPOLYLINE( list( Srf1, Srf2, Srf3, list( Crv1, Crv2, Crv3 ) ) );
  1736.  
  1737.  converts to polylines the three surfaces Srf1, Srf2, and Srf3
  1738.  and the three curves Crv1, Crv2, and Crv3.
  1739.  
  1740.                                      NIL
  1741.                                      ---
  1742.  
  1743.  ListType NIL()
  1744.  
  1745.    Creates an empty list so data can be accumulated in it.
  1746.  See CINFLECT or CZEROS for examples. See also LIST and SNOC.
  1747.  
  1748.                                   MERGEPOLY
  1749.                                   ---------
  1750.  
  1751.  PolygonType MERGEPOLY( ListType PolyList )
  1752.  
  1753.  Merges a set of polygonal objects in PolyList list to a single polygonal
  1754.  object. All elements in ObjectList must be of PolygonType type. This
  1755.  function performs the same operation as the overloaded ^ operator
  1756.  would, but might be more convenient to use under some circumstances.
  1757.  
  1758.  Example:
  1759.  
  1760.     Vrtx1 = vector( -3, -2, -1 );
  1761.     Vrtx2 = vector( 3, -2, -1 );
  1762.     Vrtx3 = vector( 3, 2, -1 );
  1763.     Vrtx4 = vector( -3, 2, -1 );
  1764.     Poly1 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) ); 
  1765.     
  1766.     Vrtx1 = vector( -3, 2, 1 );
  1767.     Vrtx2 = vector( 3, 2, 1 );
  1768.     Vrtx3 = vector( 3, -2, 1 );
  1769.     Vrtx4 = vector( -3, -2, 1 );
  1770.     Poly2 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );
  1771.     
  1772.     Vrtx1 = vector( -3, -2, 1 );
  1773.     Vrtx2 = vector( 3, -2, 1 );
  1774.     Vrtx3 = vector( 3, -2, -1 );
  1775.     Vrtx4 = vector( -3, -2, -1 );
  1776.     Poly3 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );
  1777.    
  1778.     PolyObj = MERGEPOLY( list( Poly1, Poly2, Poly3 ) );
  1779.  
  1780.                                    OFFSET
  1781.                                    ------
  1782.  
  1783.  CurveType OFFSET( CurveType Crv, NumericType OffsetDistance )
  1784.  
  1785.  or
  1786.  
  1787.  SurfaceType OFFSET( SurfaceType Srf, NumericType OffsetDistance )
  1788.  
  1789.  Offsets Crv or Srf, by translating all the control points in the
  1790.  direction of the normal of the curve or surface by an OffsetDistance
  1791.  amount. Each control point has a node parameter value associated with
  1792.  it, which is used to compute the normal. The returned curve or surface only
  1793.  approximates the real offset. One may improve the offset accuracy using
  1794.  refinement (See AOFFSET). Negative OffsetDistance denotes offset in
  1795.  the reversed direction of the normal.
  1796.  
  1797.  Example:
  1798.  
  1799.     OffCrv = OFFSET( Crv, -0.1 );
  1800.  
  1801.  offsets Crv by the amount of -0.1 in the reversed normal direction.
  1802.  See also AOFFSET.
  1803.  
  1804.                                    PDOMAIN
  1805.                                    -------
  1806.  
  1807.  ListType PDOMAIN( CurveType Crv )
  1808.  
  1809.  or
  1810.  
  1811.  ListType PDOMAIN( SurfaceType Srf )
  1812.  
  1813.    Returns the parametric domain of the curve (TMin, TMax) or of a surface
  1814.  (UMin, UMax, VMin, VMax) as a list object.
  1815.  
  1816.  Example:
  1817.  
  1818.  circ_domain = PDOMAIN( circle( vector( 0.0, 0.0, 0.0 ), 1.0 ) );
  1819.  
  1820.                                     POLY
  1821.                                     ----
  1822.  
  1823.  PolygonType POLY( ListType VrtxList, NumericType IsPolyline )
  1824.  
  1825.    Creates a single polygon/polyline (and therefore open) object, defined by
  1826.  the vertices in VrtxList (see LIST). All elements in VrtxList
  1827.  must be of VectorType type. If IsPolyline, a polyline is created,
  1828.  otherwise a polygon.
  1829.  
  1830.  Example:
  1831.  
  1832.     V1  = vector( 0.0, 0.0, 0.0 );
  1833.     V2  = vector( 0.3, 0.0, 0.0 );
  1834.     V3  = vector( 0.3, 0.0, 0.1 );
  1835.     V4  = vector( 0.2, 0.0, 0.1 );
  1836.     V5  = vector( 0.2, 0.0, 0.5 );
  1837.     V6  = vector( 0.3, 0.0, 0.5 );
  1838.     V7  = vector( 0.3, 0.0, 0.6 );
  1839.     V8  = vector( 0.0, 0.0, 0.6 );
  1840.     V9  = vector( 0.0, 0.0, 0.5 );
  1841.     V10 = vector( 0.1, 0.0, 0.5 );
  1842.     V11 = vector( 0.1, 0.0, 0.1 );
  1843.     V12 = vector( 0.0, 0.0, 0.1 );
  1844.     I = POLY( list( V1, V2, V3, V4, V5, V6, V7, V8, V9, V10, V11, V12 ),
  1845.               FALSE );
  1846.  
  1847.  constructs an object with a single polygon in the shape of the letter I.
  1848.  
  1849.                                     PRISA
  1850.                                     -----
  1851.  
  1852.  ListType PRISA( SurfaceType Srfs, NumericType SamplesPerCurve,
  1853.                  NumericType Epsilon, ConstantType Dir, VectorType Space )
  1854.  
  1855.    Computes a layout (prisa) of the given surface(s) Srfs, and returns
  1856.  a list of surface objects representing the layout.
  1857.    The surface is approximated to within Epsilon in direction Dir
  1858.  into a set of ruled surfaces and then developable surfaces that are laid out
  1859.  flat onto the XY plane. If Epsilon is negative, the piecewise ruled
  1860.  surface approximation in 3-space is returned. 
  1861.    SamplesPerCurve controls the piecewise linear approximation of the
  1862.  boundary of the ruled/developable surfaces. Space is a vector whose
  1863.  X component controls the space between the different surfaces' layout, and
  1864.  whose Y component controls the space between different layout pieces.
  1865.  
  1866.  Example:
  1867.  
  1868.  cross = cbspline( 3,
  1869.                    list( ctlpt( E3, 0.7, 0.0, 0. ),
  1870.                          ctlpt( E3, 0.7, 0.0, 0.06 ),
  1871.                          ctlpt( E3, 0.1, 0.0, 0.1 ),
  1872.                          ctlpt( E3, 0.1, 0.0, 0.6 ),
  1873.                          ctlpt( E3, 0.6, 0.0, 0.6 ),
  1874.                          ctlpt( E3, 0.8, 0.0, 0.8 ),
  1875.                          ctlpt( E3, 0.8, 0.0, 1.4 ),
  1876.                          ctlpt( E3, 0.6, 0.0, 1.6 ) ),
  1877.                    list( KV_OPEN ) );
  1878.  wglass = surfrev( cross );
  1879.  wgl_ruled = PRISA( wglass, 6, -0.1, COL, vector( 0, 0.25, 0.0 ) );
  1880.  wgl_prisa = PRISA( wglass, 6, 0.1, COL, vector( 0, 0.25, 0.0 ) );
  1881.  
  1882.  Computes a layout of a wine glass in wgl_prisa and a three-dimensional
  1883.  ruled surface approximation of wglass in wgl_ruled.
  1884.  
  1885.                                   RULEDSRF
  1886.                                   --------
  1887.  
  1888.  SurfaceType RULEDSRF( CurveType Crv1, CurveType Crv2 )
  1889.  
  1890.    Constructs a ruled surface between the two curves Crv1 and Crv2.
  1891.    The curves do not have to have the same order or type, and will be promoted
  1892.  to their least common denominator.
  1893.  
  1894.  Example:
  1895.  
  1896.     Circ = circle( vector( 0.0, 0.0, 0.0 ), 0.25 );
  1897.     Cyl = RULEDSRF( circ, circ * trans( vector( 0.0, 0.0, 1.0 ) ) );
  1898.  
  1899.  Constructs a cylinder of radius 0.25 along the Z axis from 0 to 1.
  1900.  
  1901.                                    SBEZIER
  1902.                                    -------
  1903.  
  1904.  SurfaceType SBEZIER( ListType CtlMesh )
  1905.  
  1906.    Creates a Bezier surface using the provided control mesh. CtlMesh is a
  1907.  list of rows, each of which is a list of control points. All control points
  1908.  must be of the same point type.
  1909.  
  1910.  Example:
  1911.  
  1912.    Srf = SBEZIER( list ( list( ctlpt( E3, 0.0, 0.0, 1.0 ),
  1913.                                ctlpt( E3, 0.0, 1.0, 0.0 ),
  1914.                                ctlpt( E3, 0.0, 2.0, 1.0 ) ),
  1915.                          list( ctlpt( E3, 1.0, 0.0, 0.0 ),
  1916.                                ctlpt( E3, 1.0, 1.0, 2.0 ),
  1917.                                ctlpt( E3, 1.0, 2.0, 0.0 ) ),
  1918.                          list( ctlpt( E3, 2.0, 0.0, 2.0 ),
  1919.                                ctlpt( E3, 2.0, 1.0, 0.0 ),
  1920.                                ctlpt( E3, 2.0, 2.0, 2.0 ) ),
  1921.                          list( ctlpt( E3, 3.0, 0.0, 0.0 ),
  1922.                                ctlpt( E3, 3.0, 1.0, 2.0 ),
  1923.                                ctlpt( E3, 3.0, 2.0, 0.0 ) ),
  1924.                          list( ctlpt( E3, 4.0, 0.0, 1.0 ),
  1925.                                ctlpt( E3, 4.0, 1.0, 0.0 ),
  1926.                                ctlpt( E3, 4.0, 2.0, 1.0 ) ) ) );
  1927.  
  1928.                                   SBSPLINE
  1929.                                   --------
  1930.  
  1931.  SurfaceType SBSPLINE( NumericType UOrder, NumericType VOrder,
  1932.                        ListType CtlMesh, ListType KnotVectors )
  1933.  
  1934.    Creates a Bspline surface from the provided UOrder and VOrder
  1935.  orders, the control mesh CtlMesh, and the two knot vectors KnotVectors.
  1936.  CtlMesh is a list of rows, each of which is a list of control points.
  1937.  All control points must be of the same point type. KnotVectors is a
  1938.  list of two knot vectors. Each knot vector is a list of NumericType knots or a
  1939.  list of a single constant KV_OPEN or KV_FLOAT, in which a uniform knot
  1940.  vector with the appropriate length and with open or floating end condition
  1941.  will be constructed automatically.
  1942.  
  1943.  Example:
  1944.  
  1945.     Mesh = list ( list( ctlpt( E3, 0.0, 0.0, 1.0 ),
  1946.                         ctlpt( E3, 0.0, 1.0, 0.0 ),
  1947.                         ctlpt( E3, 0.0, 2.0, 1.0 ) ),
  1948.                   list( ctlpt( E3, 1.0, 0.0, 0.0 ),
  1949.                         ctlpt( E3, 1.0, 1.0, 2.0 ),
  1950.                         ctlpt( E3, 1.0, 2.0, 0.0 ) ),
  1951.                   list( ctlpt( E3, 2.0, 0.0, 2.0 ),
  1952.                         ctlpt( E3, 2.0, 1.0, 0.0 ),
  1953.                         ctlpt( E3, 2.0, 2.0, 2.0 ) ),
  1954.                   list( ctlpt( E3, 3.0, 0.0, 0.0 ),
  1955.                         ctlpt( E3, 3.0, 1.0, 2.0 ),
  1956.                         ctlpt( E3, 3.0, 2.0, 0.0 ) ),
  1957.                   list( ctlpt( E3, 4.0, 0.0, 1.0 ),
  1958.                         ctlpt( E3, 4.0, 1.0, 0.0 ),
  1959.                         ctlpt( E3, 4.0, 2.0, 1.0 ) ) );
  1960.     Srf = SBSPLINE( 3, 3, Mesh, list( list( KV_OPEN ),
  1961.                                       list( 3, 3, 3, 4, 5, 6, 6, 6 ) ) );
  1962.  
  1963.  constructs a bi-quadratic Bspline surface with its first knot vector
  1964.  having uniform knot spacing with open end conditions.
  1965.  
  1966.                                    SDERIVE
  1967.                                    -------
  1968.  
  1969.  SurfaceType SDERIVE( SurfaceType Srf, NumericType Dir )
  1970.  
  1971.    Returns a vector field surface representing the differentiated surface
  1972.  in the given direction (ROW or COL). Evaluation of the returned surface at
  1973.  a given parameter value will return a vector tangent to Srf in
  1974.  Dir at that parameter value.
  1975.  
  1976.  DuSrf = SDERIVE( Srf, ROW );
  1977.  DvSrf = SDERIVE( Srf, COL );
  1978.  Normal = coerce( seval( DuSrf, 0.5, 0.5 ), VECTOR_TYPE ) ^
  1979.           coerce( seval( DvSrf, 0.5, 0.5 ), VECTOR_TYPE );
  1980.  
  1981.  computes the two partial derivatives of the surface Srf and computes
  1982.  its normal as their cross product, at the parametric location (0.5, 0.5).
  1983.  
  1984.                                    SDIVIDE
  1985.                                    -------
  1986.  
  1987.  SurfaceType SDIVIDE( SurfaceType Srf, ConstantType Direction,
  1988.                                                           NumericType Param )
  1989.  
  1990.    Subdivides a surface into two at the specified parameter value Param
  1991.  in the specified Direction (ROW or COL). Srf can be either a Bspline
  1992.  surface in which Param must be conatined in the parametric domain of the
  1993.  surface, or a Bezier surface in which Param must be in the range of zero
  1994.  to one.
  1995.  
  1996.    It returns a list of the two sub-surfaces. The individual surfaces may be
  1997.  extracted from the list using the NTH command.
  1998.  
  1999.  Example:
  2000.  
  2001.     SrfLst = SDIVIDE( Srf, ROW, 0.5 );
  2002.     Srf1 = nth( SrfLst, 1 );
  2003.     Srf2 = nth( SrfLst, 2 );
  2004.  
  2005.  subdivides Srf at the parameter value of 0.5 in the ROW direction.
  2006.  
  2007.                                    SEDITPT
  2008.                                    -------
  2009.  
  2010.  SurfaceType SEDITPT( SurfaceType Srf, CtlPtType CPt, NumericType UIndex,
  2011.                                                       NumericType VIndex )
  2012.  
  2013.    Provides a simple mechanism to manually modify a single control point number
  2014.  UIndex and VIndex (base count is 0) in the control mesh of Srf
  2015.  by substituting CtlPt instead. CtlPt must have the same point type as
  2016.  the control points of Srf. Original surface Srf is not modified.
  2017.  
  2018.  Example:
  2019.  
  2020.     CPt = ctlpt( E3, 1, 2, 3 );
  2021.     NewSrf = SEDITPT( Srf, CPt, 0, 0 );
  2022.  
  2023.  constructs a NewSrf with the first control point of Srf being
  2024.  CPt.
  2025.  
  2026.                                     SEVAL
  2027.                                     -----
  2028.  
  2029.  CtlPtType SEVAL( SurfaceType Srf, NumericType UParam, NumericType VParam )
  2030.  
  2031.    Evaluates the provided surface Srf at the given UParam and
  2032.  VParam values. Both UParam and VParam should be contained
  2033.  in the surface parametric domain if Srf is a Bspline surface, or
  2034.  between zero and one if Srf is a Bezier surface. The returned control
  2035.  point has the same type as the control points of Srf.
  2036.  
  2037.  Example:
  2038.  
  2039.     CPt = SEVAL( Srf, 0.25, 0.22 );
  2040.  
  2041.  evaluates Srf at the parameter values of (0.25, 0.22).
  2042.  
  2043.                                   SFROMCRVS
  2044.                                   ---------
  2045.  
  2046.  SurfaceType SFROMCRVS( ListType CrvList, NumericType OtherOrder )
  2047.  
  2048.    Constructs a surface by substituting the curves in CrvList as rows
  2049.  in a control mesh of a surface. Curves in CrvList are made compatible
  2050.  by promoting Bezier curves to Bsplines if necessary, and raising degree
  2051.  and refining as required before substituting the control polygons of the
  2052.  curves as rows in the mesh. The other direction order is set by
  2053.  OtherOrder, which cannot be larger than the number of curves.
  2054.  
  2055.    The surface interpolates the first and last curves only.
  2056.  
  2057.  Example:
  2058.  
  2059.     Crv1 = cbspline( 3,
  2060.                      list( ctlpt( E3, 0.0, 0.0, 0.0 ),
  2061.                            ctlpt( E3, 1.0, 0.0, 0.0 ),
  2062.                            ctlpt( E3, 1.0, 1.0, 0.0 ) ),
  2063.                      list( KV_OPEN ) );
  2064.     Crv2 = Crv1 * trans( vector( 0.0, 0.0, 1.0 ) );
  2065.     Crv3 = Crv2 * scale( vector( 0.0, 0.0, 2.0 ) )
  2066.                 * trans( vector( 0.1, 0.1, 0.1 ) );
  2067.     Srf = SFROMCRVS( list( Crv1, Crv2, Crv3 ), 3 );
  2068.  
  2069.                                    SMERGE
  2070.                                    ------
  2071.  
  2072.  SurfaceType SMERGE( SurfaceType Srf1, SurfaceType Srf2,
  2073.                      NumericType Dir, NumericType SameEdge )
  2074.  
  2075.  Merges two surfaces along the requested direction (ROW or COL). If
  2076.  SameEdge is non-zero (ON or TRUE), then the common edge is assumed to be
  2077.  identical and copied only once. Otherwise (OFF or FALSE), a ruled surface
  2078.  is constructed between the two surfaces along the (not) common edge.
  2079.  
  2080.  Example:
  2081.  
  2082.  MergedSrf = SMERGE( Srf1, Srf2, ROW, TRUE );
  2083.  
  2084.                                    SMORPH
  2085.                                    ------
  2086.  
  2087.  SurfaceType SMORPH( SurfaceType Srf1, SurfaceType Srf2, NumericType Blend )
  2088.  
  2089.  Creates a new surface which is a convex blend of the two given surfaces.
  2090.  The two given surfaces must be compatible (see FFCOMPAT) before this blend
  2091.  is invoked. Very useful if a sequence that "morphs" one surface to another
  2092.  is to be created.
  2093.  
  2094.  Example:
  2095.  
  2096.  for ( i = 0.0, 1.0, 11.0,
  2097.         Msrf = SMORPH( Srf1, Srf2, i / 11.0 ):
  2098.         color( Msrf, white ):
  2099.         attrib( Msrf, "rgb", "255,255,255" ):
  2100.         attrib( Msrf, "reflect", 0.7 ):
  2101.         save( "morp1-" + i, Msrf )
  2102.  );
  2103.  
  2104.  creates a sequence of 12 surfaces, morphed from Srf1 to Srf2
  2105.  and saves them in the files "morph-0.dat" to "morph-11.dat".
  2106.  
  2107.                                    SNORMAL
  2108.                                    -------
  2109.  
  2110.  VectorType SNORMAL( SurfaceType Srf, NumericType UParam, NumericType VParam )
  2111.  
  2112.    Computes the normal vector to Srf at the parameter values UParam
  2113.  and VParam. The returned vector has a unit length.
  2114.  
  2115.  Example:
  2116.  
  2117.     Normal = SNORMAL( Srf, 0.5, 0.5 );
  2118.  
  2119.  computes the normal to Srf at the parameter values (0.5, 0.5).
  2120.  See also SNRMLSRF.
  2121.  
  2122.                                   SNRMLSRF
  2123.                                   --------
  2124.  
  2125.  SurfaceType SNRMLSRF( SurfaceType Srf )
  2126.  
  2127.  Symbolically computes a vector field surface representing the non-normalized
  2128.  normals of the given surface. That is the normal surface, evaluated at
  2129.  (u, v), provides a vector in the direction of the normal of the original
  2130.  surface at (u, v). The normal surface is computed as the symbolic cross
  2131.  product of the two surfaces representing the partial derivatives of the
  2132.  original surface.
  2133.  
  2134.  Example:
  2135.  
  2136.  NrmlSrf = SNRMLSRF( Srf );
  2137.  
  2138.                                    SPHERE
  2139.                                    ------
  2140.  
  2141.  PolygonType SPHERE( VectorType Center, NumericType Radius )
  2142.  
  2143.    Creates a SPHERE geometric object, defined by Center as the center of
  2144.  the SPHERE, and with Radius as the radius of the SPHERE.
  2145.    See RESOLUTION for accuracy of SPHERE approximation as a polygonal model. 
  2146.  
  2147.                                    SRAISE
  2148.                                    ------
  2149.  
  2150.  SurfaceType SRAISE( SurfaceType Srf, ConstantType Direction,
  2151.                                                       NumericType NewOrder )
  2152.  
  2153.    Raises Srf to the specified NewOrder in the specified
  2154.  Direction.
  2155.  
  2156.  Example:
  2157.  
  2158.     Srf = ruledSrf( cbezier( list( ctlpt( E3, -0.5, -0.5, 0.0 ),
  2159.                                    ctlpt( E3,  0.5, -0.5, 0.0 ) ) ),
  2160.                     cbezier( list( ctlpt( E3, -0.5,  0.5, 0.0 ),
  2161.                                    ctlpt( E3,  0.5,  0.5, 0.0 ) ) ) );
  2162.     Srf = SRAISE( SRAISE( Srf, ROW, 3 ), COL, 3 );
  2163.  
  2164.  constructs a bilinear flat ruled surface and raises both its directions to be
  2165.  a bi-quadratic surface.
  2166.  
  2167.                                    SREFINE
  2168.                                    -------
  2169.  
  2170.  SurfaceType SREFINE( SurfaceType Srf, ConstantType Direction,
  2171.                       NumericType Replace, ListType KnotList )
  2172.  
  2173.    Provides the ability to Replace a knot vector of Srf or refine 
  2174.  it in the specified direction Direction (ROW or COL).
  2175.    KnotList is a list of knots to refine Srf at. All knots should be
  2176.  contained in the parametric domain of Srf in Direction. If the knot
  2177.  vector is replaced, the length of KnotList should be identical to the
  2178.  length of the original knot vector of Srf in Direction. If Srf
  2179.  is a Bezier surface, it is automatically promoted to be a Bspline surface.
  2180.  
  2181.  Example:
  2182.  
  2183.     Srf = SREFINE( SREFINE( Srf,
  2184.                             ROW, FALSE, list( 0.333, 0.667 ) ),
  2185.                    COL, FALSE, list( 0.333, 0.667 ) );
  2186.  
  2187.  refines Srf in both directions by adding two more knots at 0.333 and
  2188.  0.667
  2189.  
  2190.                                    SREGION
  2191.                                    -------
  2192.  
  2193.  SurfaceType SREGION( SurfaceType Srf, ConstantType Direction,
  2194.                                                         NumericType NewOrder )
  2195.  
  2196.    Extracts a region of Srf between MinParam and MaxParam
  2197.  in the specified Direction. Both MinParam and MaxParam
  2198.  should be contained in the parametric domain of Srf in Direction.
  2199.  
  2200.  Example:
  2201.  
  2202.     SubSrf = SREGION( Srf, COL, 0.3, 0.6 );
  2203.  
  2204.  extracts the region of Srf from the parameter value 0.3 to the
  2205.  parameter value 0.6 along the COLumn direction. the ROW direction is
  2206.  extracted as a whole.
  2207.  
  2208.                                   STANGENT
  2209.                                   --------
  2210.  
  2211.  VectorType STANGENT( SurfaceType Srf, ConstantType Direction,
  2212.                       NumericType UParam, NumericType VParam )
  2213.  
  2214.    Computes the tangent vector to Srf at the parameter values UParam
  2215.  and VParam in Direction. The returned vector has a unit length.
  2216.  
  2217.  Example:
  2218.  
  2219.     Tang = STANGENT( Srf, ROW, 0.5, 0.6 );
  2220.  
  2221.  computes the tangent to Srf in the ROW direction at the parameter
  2222.  values (0.5, 0.6).
  2223.  
  2224.                                    SURFREV
  2225.                                    -------
  2226.  
  2227.  PolygonType SURFREV( PolygonType Object )
  2228.  
  2229.  or
  2230.  
  2231.  SurfaceType SURFREV( CurveType Object )
  2232.  
  2233.    Creates a surface of revolution by rotating the first polygon/curve of the
  2234.  given Object, around the Z axis. Use the linear transformation function
  2235.  to position a surface of revolution in a different orientation.
  2236.  
  2237.  Example:
  2238.  
  2239.     VTailAntn = SURFREV( ctlpt( E3, 0.001, 0.0, 1.0 ) +
  2240.                          ctlpt( E3, 0.01,  0.0, 1.0 ) +
  2241.                          ctlpt( E3, 0.01,  0.0, 0.8 ) +
  2242.                          ctlpt( E3, 0.03,  0.0, 0.7 ) +
  2243.                          ctlpt( E3, 0.03,  0.0, 0.3 ) +
  2244.                          ctlpt( E3, 0.001, 0.0, 0.0 ) );
  2245.  
  2246.  constructs a piecewise linear Bspline curve in the XZ plane and uses it to
  2247.  construct a surface of revolution by rotating it around the Z axis.
  2248.  
  2249.                                   SWEEPSRF
  2250.                                   --------
  2251.  
  2252.  SurfaceType SWEEPSRF( CurveType CrossSection, CurveType Axis,
  2253.                      NumericType Scale | CurveType ScaleCrv,
  2254.                      CurveType FrameCrv | VectorType FrameVec | ConstType OFF )
  2255.  
  2256.    Constructs a generalized cylinder surface. This function sweeps a specified
  2257.  cross-section CrossSection along the provided Axis.
  2258.  The cross-section may be scaled by a constant value Scale, or scaled
  2259.  along the Axis parametric direction via a scaling curve ScaleCrv.
  2260.    By default, when frame specification is OFF, the orientation
  2261.  of the cross section is computed using the Axis curve tangent and
  2262.  normal. However, unlike the Frenet frame, attempt is made to minimize
  2263.  the normal change, as can happen along inflection points in Axis.
  2264.    If a VectorType FrameVec is provided as a frame orientation setting,
  2265.  it is used to fix the normal direction to this value. In other words, the
  2266.  orientation frame has a fixed normal. If a CurveType FrameCrv is
  2267.  specified as a frame orientation setting, this vector field curve is
  2268.  evaluated at each placement of the cross-section to yield the needed normal.
  2269.  
  2270.    The resulting sweep is only an approximation of the real sweep. The
  2271.  scaling and axis placement will not be exact, in general.
  2272.    Refinement of the axis curve at the proper location, where accuracy is
  2273.  important, should improve the accuracy of the output. The parametric domains
  2274.  of ScaleCrv and FrameCrv do not have to match the parametric
  2275.  domain of Axis, and their domains are made compatible by this function.
  2276.  
  2277.  Example:
  2278.  
  2279.     Cross = arc( vector( 0.2, 0.0, 0.0 ),
  2280.                  vector( 0.2, 0.2, 0.0 ),
  2281.                  vector( 0.0, 0.2, 0.0 ) ) +
  2282.             arc( vector( 0.0, 0.4, 0.0 ),
  2283.                  vector( 0.1, 0.4, 0.0 ),
  2284.                  vector( 0.1, 0.5, 0.0 ) ) +
  2285.             arc( vector( 0.8, 0.5, 0.0 ),
  2286.                  vector( 0.8, 0.3, 0.0 ),
  2287.                  vector( 1.0, 0.3, 0.0 ) ) +
  2288.             arc( vector( 1.0, 0.1, 0.0 ),
  2289.                  vector( 0.9, 0.1, 0.0 ),
  2290.                  vector( 0.9, 0.0, 0.0 ) ) +
  2291.             ctlpt( E2, 0.2, 0.0 );
  2292.     Axis = arc( vector( -1.0, 0.0, 0.0 ),
  2293.                 vector(  0.0, 0.0, 0.1 ),
  2294.                 vector(  1.0, 0.0, 0.0 ) );
  2295.     Axis = crefine( Axis, FALSE, list( 0.25, 0.5, 0.75 ) );
  2296.     ScaleCrv = cbezier( list( ctlpt( E2, 0.0, 0.01 ),
  2297.                               ctlpt( E2, 1.0, 0.5 ),
  2298.                               ctlpt( E2, 2.0, 0.01 ) ) );
  2299.     Srf1 = SWEEPSRF( Cross, Axis, ScaleCrv, OFF );
  2300.     Srf2 = SWEEPSRF( Cross, Axis, ScaleCrv, vector( 0.0, 1.0, 1.0 ) );
  2301.     Srf3 = SWEEPSRF( Cross, Axis, ScaleCrv,
  2302.                      cbezier( list( ctlpt( E3,  1.0, 0.0, 0.0 ),
  2303.                                     ctlpt( E3,  0.0, 1.0, 0.0 ),
  2304.                                     ctlpt( E3, -1.0, 0.0, 0.0 ) ) ) );
  2305.  
  2306.  
  2307.  constructs a rounded rectangle cross-section and sweeps it along an arc, while
  2308.  scaling and orienting in several ways. The axis curve Axis is
  2309.  manually refined to better approximate the requested scaling.
  2310.  
  2311.                                   SYMBPROD
  2312.                                   --------
  2313.  
  2314.  CurveType SYMBPROD( CurveType Crv1, CurveType Crv2 )
  2315.  
  2316.  or
  2317.  
  2318.  SurfaceType SYMBPROD( SurfaceType Srf1, SurfaceType Srf2 )
  2319.  
  2320.  Computes the symbolic product of the given two curves or surfaces as
  2321.  a curve or surface. The product is computed coordinate-wise.
  2322.  
  2323.  Example:
  2324.  
  2325.  ProdSrf = SYMBPROD( Srf1, Srf2 )
  2326.  
  2327.                                   SYMBDPROD
  2328.                                   ---------
  2329.  
  2330.  CurveType SYMBDPROD( CurveType Crv1, CurveType Crv2 )
  2331.  
  2332.  or
  2333.  
  2334.  SurfaceType SYMBDPROD( SurfaceType Srf1, SurfaceType Srf2 )
  2335.  
  2336.  Computes the symbolic dot (inner) product of the given two curves or surfaces
  2337.  as a scalar curve or surface.
  2338.  
  2339.  Example:
  2340.  
  2341.  DiffCrv = symbdiff( Crv1, Crv2 )
  2342.  DistSqrCrv = SYMBDPROD( DiffCrv, DiffCrv )
  2343.  
  2344.  Computes a scalar curve that at parameter t is equal to the distance
  2345.  square between Crv1 at t and Crv2.
  2346.  
  2347.                                   SYMBCPROD
  2348.                                   ---------
  2349.  
  2350.  CurveType SYMBCPROD( CurveType Crv1, CurveType Crv2 )
  2351.  
  2352.  or
  2353.  
  2354.  SurfaceType SYMBCPROD( SurfaceType Srf1, SurfaceType Srf2 )
  2355.  
  2356.  Computes the symbolic cross product of the given two curves or surfaces as
  2357.  a curve or surface.
  2358.  
  2359.  Example:
  2360.  
  2361.  NrmlSrf = SYMBCPROD( sderive( Srf, ROW ), sderive( Srf, COL ) )
  2362.  
  2363.  computes a normal surface as the cross product of the surface two partial
  2364.  derivatives (see SNRMLSRF).
  2365.  
  2366.                                    SYMBSUM
  2367.                                    -------
  2368.  
  2369.  CurveType SYMBSUM( CurveType Crv1, CurveType Crv2 )
  2370.  
  2371.  or
  2372.  
  2373.  SurfaceType SYMBSUM( SurfaceType Srf1, SurfaceType Srf2 )
  2374.  
  2375.  Computes the symbolic sum of the given two curves or surfaces as
  2376.  a curve or surface. The sum is computed coordinate-wise.
  2377.  
  2378.  Example:
  2379.  
  2380.  SumCrv = SYMBSUM( Crv1, Crv2 )
  2381.  
  2382.                                   SYMBDIFF
  2383.                                   --------
  2384.  
  2385.  CurveType SYMBDIFF( CurveType Crv1, CurveType Crv2 )
  2386.  
  2387.  or
  2388.  
  2389.  SurfaceType SYMBDIFF( SurfaceType Srf1, SurfaceType Srf2 )
  2390.  
  2391.  Computes the symbolic difference of the given two curves or surfaces as
  2392.  a curve or surface. The difference is computed coordinate-wise.
  2393.  
  2394.  Example:
  2395.  
  2396.  DiffCrv = SYMBDIFF( Crv1, Crv2 )
  2397.  DistSqrCrv = symbdprod( DiffCrv, DiffCrv )
  2398.  
  2399.  
  2400.                                     TORUS
  2401.                                     -----
  2402.  
  2403.  PolygonType TORUS( VectorType Center, VectorType Normal,
  2404.                     NumericType MRadius, NumericType mRadius )
  2405.  
  2406.    Creates a TORUS geometric object, defined by Center as the center
  2407.  of the TORUS, Normal as the normal to the main plane of the TORUS,
  2408.  MRadius and mRadius as the major and minor radii of the TORUS.
  2409.    See RESOLUTION for the accuracy of the TORUS approximation as a polygonal
  2410.  model. 
  2411.  
  2412.  Example:
  2413.  
  2414.     T = TORUS( vector( 0.0, 0.0, 0.0), vector( 0.0, 0.0, 1.0), 0.5, 0.2 );
  2415.  
  2416.  constructs a torus with major plane as the XY plane, major radius of 0.5,
  2417.  and minor radius of 0.2.
  2418.  
  2419.  
  2420.                        Object transformation functions
  2421.                        -------------------------------
  2422.  
  2423.  All the routines in this section construct a 4 by 4 homogeneous
  2424.  transformation matrix representing the required transform. These matrices
  2425.  may be concatenated to achieve more complex transforms using the matrix
  2426.  multiplication operator *. For example, the expression
  2427.  
  2428.     m = trans( vector( -1, 0, 0 ) ) * rotx( 45 ) * trans( vector( 1, 0, 0 ) );
  2429.  
  2430.  constructs a transform to rotate an object around the X = 1 line, 45 degrees.
  2431.  A matrix representing the inverse transformation can be computed as:
  2432.     InvM = m ^ -1
  2433.  See also overloading of the - operator.
  2434.  
  2435.                                    HOMOMAT
  2436.                                    -------
  2437.  
  2438.  MatrixType HOMOMAT( ListType MatData )
  2439.  
  2440.    Creates an arbitrary homogeneous transformation matrix by manually providing
  2441.  its 16 coefficients.
  2442.  Example:
  2443.  
  2444.  for ( a = 1, 1, 720 / step,
  2445.        view_mat = save_mat *
  2446.                   HOMOMAT( list( list( 1, 0, 0, 0 ),
  2447.                                  list( 0, 1, 0, 0 ),
  2448.                                  list( 0, 0, 1, -a * step / 500 ),
  2449.                                  list( 0, 0, 0, 1 ) ) ):
  2450.        view(list(view_mat, b, axes), on)
  2451.  );
  2452.  
  2453.  looping and viewing through a sequence of perspective transforms, created
  2454.  using the HOMOMAT constructor.
  2455.  
  2456.                                     ROTX
  2457.                                     ----
  2458.  
  2459.  MatrixType ROTX( NumericType Angle )
  2460.  
  2461.    Creates a rotation around the X transformation matrix with Angle degrees.
  2462.  
  2463.                                     ROTY
  2464.                                     ----
  2465.  
  2466.  MatrixType ROTY( NumericType Angle )
  2467.  
  2468.    Creates a rotation around te Y transformation matrix with Angle degrees.
  2469.  
  2470.                                     ROTZ
  2471.                                     ----
  2472.  
  2473.  MatrixType ROTZ( NumericType Angle )
  2474.  
  2475.    Creates a rotation around the Z transformation matrix with Angle degrees.
  2476.  
  2477.                                     SCALE
  2478.                                     -----
  2479.  
  2480.  MatrixType SCALE( VectorType ScaleFactors )
  2481.  
  2482.    Creates a scaling by the ScaleFactors transformation matrix.
  2483.  
  2484.                                     TRANS
  2485.                                     -----
  2486.  
  2487.  MatrixType TRANS( VectorType TransFactors )
  2488.  
  2489.    Creates a translation by the TransFactors transformation matrix.
  2490.  
  2491.                          General purpose functions  
  2492.                          ---------------------------
  2493.  
  2494.                                    ATTRIB
  2495.                                    ------
  2496.  
  2497.  ATTRIB( AnyType Object, StringType Name, StringType Value )
  2498.  
  2499.  or
  2500.  
  2501.  ATTRIB( AnyType Object, StringType Name, RealType Value )
  2502.  
  2503.    Provides a mechanism to add a string or numeric attribute to an Object,
  2504.  with name Name and value Value.
  2505.  
  2506.    These attributes may be used to pass information to other programs about
  2507.  this object, and are saved with the objects in data files. For example,
  2508.  
  2509.     ATTRIB(Glass, "rgb", "255,0,0");
  2510.     ATTRIB(Glass, "reflect", 1.4);
  2511.  
  2512.  sets the RGB color of the Glass object.
  2513.  
  2514.    Attribute names are case insensitive. Spaces are allowed in the Value
  2515.  string, as well as the double quote itself, although the latter must be
  2516.  escaped:
  2517.  
  2518.     ATTRIB(Glass, "text", "Say "this is me"");
  2519.  
  2520.                                     COLOR
  2521.                                     -----
  2522.  
  2523.  COLOR( GeometricType Object, NumericType Color )
  2524.  
  2525.    Sets the color of the object to one of those specified below. Note that an
  2526.  object has a default color (see IRIT.CFG file) according to its origin -
  2527.  loaded with the LOAD command, PRIMITIVE, or BOOLEAN operation result.
  2528.    The system internally supports colors (although you may have a B&W system)
  2529.  and the colors recognized are:
  2530.  BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, YELLOW, and WHITE.
  2531.  
  2532.    See the ATTRIB command for more fine control of colors using the RGB
  2533.  attribute. 
  2534.  
  2535.                                    COMMENT
  2536.                                    -------
  2537.  
  2538.  COMMENT
  2539.  
  2540.  Two types of comments are allowed:
  2541.  
  2542.  1. One-line comment: starts anywhere in a line at the '#' character, up to
  2543.     the end of the line.
  2544.  
  2545.  2. Block comment: starts at the COMMENT keyword followed by a unique
  2546.     character (anything but white space), up to the second occurrence of that
  2547.     character. This is a fast way to comment out large blocks.
  2548.  
  2549.  Example:
  2550.  
  2551.     COMMENT 
  2552.       This is a comment
  2553.     
  2554.  
  2555.                                     EXIT
  2556.                                     ----
  2557.  
  2558.  EXIT();
  2559.  
  2560.    Exits from the solid modeler. NO warning is given!
  2561.  
  2562.                                      FOR
  2563.                                      ---
  2564.  
  2565.  FOR( NumericType Start, NumericType Increment, NumericType End, AnyType Body )
  2566.  
  2567.    Executes the Body (see below), while the FOR loop conditions hold.
  2568.    Start, Increment, End are evaluated first, and the loop is executed
  2569.  while <= End if Increment > 0, or while >= End if Increment < 0.
  2570.    If Start is of the form "Variable = Expression", then that variable is
  2571.  updated on each iteration, and can be used within the body.
  2572.    The body may consist of any number of regular commands, separated by
  2573.  COLONs, including nesting FOR loops to an arbitrary level.
  2574.  
  2575.  Example:
  2576.  
  2577.  step = 10;
  2578.  rotstepx = rotx(step);
  2579.  FOR ( a = 1, 1, 360 / step,
  2580.      view_mat = rotstepx * view_mat:
  2581.      view( list( view_mat, b, axes ), ON )
  2582.  );
  2583.  
  2584.  Displays b and axes with a view direction that is rotated 10 degrees at a
  2585.  time around the X axis.
  2586.  
  2587.                                     HELP
  2588.                                     ----
  2589.  
  2590.  HELP( StringType Subject )
  2591.  
  2592.    Provides help on the specified Subject.
  2593.  
  2594.  Example:
  2595.  
  2596.     HELP("");
  2597.  
  2598.  will list all IRIT help subjects.
  2599.  
  2600.                                     FREE
  2601.                                     ----
  2602.  
  2603.  FREE( GeometricType Object )
  2604.  
  2605.    Because of the usually huge size of geometric objects, this procedure
  2606.  may be used to free them. Reassigning a value (even of different type)
  2607.  to a variable automatically releases the old variable's allocated space
  2608.  as well.
  2609.  
  2610.                                   FUNCTION
  2611.                                   --------
  2612.  
  2613.  FuncName = FUNCTION(Prm1, Prm2, ... , PrmN):LclVal1:LclVar2: ... :LclVarM:
  2614.      FuncBody;
  2615.  
  2616.  Defines a function named FuncName with N parameters and M local variables
  2617.  (N, M >= 0). Here is a (simple) example of a function with no local variables
  2618.  and a single parameter that computes the square of a number:
  2619.  
  2620.  sqr = FUNCTION(x):
  2621.     return = x * x;
  2622.  
  2623.    Functions can be defined with optional parameters and optional local
  2624.  variables. A function's body may contain an arbitrary set of expressions
  2625.  including for loops, (user) function calls, or even recursive function calls,
  2626.  all separated by colons.
  2627.    The returned value of the function is the value of an automatically defined
  2628.  local variable named return. The return variable is a regular local variable
  2629.  within the scope of the function and can be used as any other variable.
  2630.  
  2631.    If a variable's name is found in neither the local variable list nor
  2632.  the parameter list, it is searched in the global variable list (outside
  2633.  the scope of the function). Binding of names of variables is static as in the
  2634.  C programming language.
  2635.  
  2636.    Because binding of variables is performed in execution time, there is a
  2637.  somewhat less restrictive type checking of parameters of functions that are
  2638.  invoked within a user's defined function.
  2639.  
  2640.    A function can invoke itself, i.e., it can be recursive. However, since a
  2641.  function should be defined when it is called, a dummy function should be
  2642.  defined before the recursive one is defined:
  2643.  
  2644.  factorial = function(x):return = x; # Dummy function.
  2645.  factorial = function(x):
  2646.      if (x <= 1, return = 1, return = x * factorial(x - 1));
  2647.  
  2648.    Overloading is valid inside a function as it is outside. For example, for
  2649.  
  2650.  add = FUNCTION(x, y):
  2651.     return = x + y;
  2652.  
  2653.  the following function calls are all valid:
  2654.  
  2655.  add(1, 2);
  2656.  add(vector(1,2,3), point(1,2,3));
  2657.  add(box(vector(-3, -2, -1), 6, 4, 2), box(vector(-4, -3, -2), 2, 2, 4));
  2658.  
  2659.  Finally, here is a more interesting example that computes an approximation
  2660.  of the length of a curve, using the sqr function defined above:
  2661.  
  2662.  distptpt = FUNCTION(pt1, pt2):
  2663.      return = sqrt(sqr(coord(pt1, 1) - coord(pt2, 1)) +
  2664.                    sqr(coord(pt1, 2) - coord(pt2, 2)) +
  2665.                    sqr(coord(pt1, 3) - coord(pt2, 3)));
  2666.  
  2667.  crvlength = FUNCTION(crv, n):pd:t:t1:t2:dt:pt1:pt2:i:
  2668.      return = 0.0:
  2669.      pd = pdomain(crv):
  2670.      t1 = nth(pd, 1):
  2671.      t2 = nth(pd, 2):
  2672.      dt = (t2 - t1) / n:
  2673.      pt1 = coerce(ceval(crv, t1), e3):
  2674.      for (i = 1, 1, n,
  2675.           pt2 = coerce(ceval(crv, t1 + dt * i), e3):
  2676.           return = return + distptpt(pt1, pt2):
  2677.           pt1 = pt2);
  2678.  
  2679.  Try, for example:
  2680.  
  2681.  crvlength(circle(vector(0.0, 0.0, 0.0), 1.0), 30) / 2;
  2682.  crvlength(circle(vector(0.0, 0.0, 0.0), 1.0), 100) / 2;
  2683.  crvlength(circle(vector(0.0, 0.0, 0.0), 1.0), 300) / 2;
  2684.  
  2685.  See PROCEDURE for more.
  2686.  
  2687.                                      IF
  2688.                                      --
  2689.  
  2690.  IF( NumericType Cond, AnyType TrueBody { , AnyType FalseBody } )
  2691.  
  2692.    Executes TrueBody (group of regular commands, separated by COLONs -
  2693.  see FOR loop) if the Cond holds, i.e., it is a numeric value other than
  2694.  zero, or optionally, if it exists, executes FalseBody if the Cond
  2695.  does not hold, i.e., it evaluates to a numeric value equal to zero.
  2696.  
  2697.  Examples:
  2698.  
  2699.     IF ( machine == IBMOS2, resolution = 5, resolution = 10 );
  2700.     IF ( a > b, max = a, max = b );
  2701.  
  2702.  sets the resolution to be 10, unless running on an IBMOS2 system, in which
  2703.  case the resolution variable will be set to 5 in the first statement, and
  2704.  set max to the maximum of a and b in the second statement.
  2705.  
  2706.                                    INCLUDE
  2707.                                    -------
  2708.  
  2709.  INCLUDE( StringType FileName )
  2710.  
  2711.    Executes the script file FileName. Nesting of include file is allowed up
  2712.  to 10 levels deep. If an error occurs, all open files in all nested files
  2713.  are closed and data are waited for at the top level (standard input).
  2714.  
  2715.    A script file can contain any command the solid modeler supports.
  2716.  
  2717.  Example:
  2718.  
  2719.     INCLUDE( "general.irt" );
  2720.  
  2721.  includes the file "general.irt".
  2722.  
  2723.                                   INTERACT
  2724.                                   --------
  2725.  
  2726.  INTERACT( GeometryTreeType Object )
  2727.  
  2728.    A user-defined function (see iritinit.irt) that does the following,
  2729.  in order:
  2730.  Clear the display device.
  2731.  Display the given Object.
  2732.  Pause for a keystroke.
  2733.  
  2734.    This user-defined function in version 4.0 of IRIT is an
  2735.  emulation of the INTERACT function that used to exist in previous versions.
  2736.  
  2737.  Example:
  2738.  
  2739.  INTERACT( list( view_mat, Axes, Obj ) );
  2740.  
  2741.  displays and interacts with the object Obj and the predefined object
  2742.  Axes. VIEW_MAT will be used to set the starting transformation.
  2743.  
  2744.    See VIEW and VIEWOBJ for more.
  2745.  
  2746.                                     LIST
  2747.                                     ----
  2748.  
  2749.  ListType LIST( AnyType Elem1, AnyType Elem2, ... )
  2750.  
  2751.    Constructs an object as a list of several other objects. Only a reference
  2752.  is made to the Elements, so modifying Elem1 after being included in the list
  2753.  will affect Elem1 in that list next time list is used!
  2754.  
  2755.    Each inclusion of an object in a list increases its internal used
  2756.  reference. The object is freed iff in used reference is zero.
  2757.    As a result, attempt to delete a variable (using FREE) which is referenced
  2758.  in a list removes the variable, but the object itself is freed only when the
  2759.  list is freed.
  2760.  
  2761.                                     LOAD
  2762.                                     ----
  2763.  
  2764.  AnyType LOAD( StringType FileName )
  2765.  
  2766.    Loads an object from the given FileName. The object may be any object
  2767.  defined in the system, including lists, in which the structure is recovered
  2768.  and reconstructed as well (internal objects are inserted into the global
  2769.  system object list if they have names). If no file type is provided, ".dat"
  2770.  is assumed.
  2771.  
  2772.    Under unix, compressed files can be loaded if the given file name has
  2773.  a postfix of ".Z". The unix system's "zcat" will be invoked via a pipe
  2774.  for that purpose.
  2775.  
  2776.                                    LOGFILE
  2777.                                    -------
  2778.  
  2779.  LOGFILE( NumericType Set )
  2780.  
  2781.    If Set is non zero (see TRUE/FALSE and ON/OFF), then everything
  2782.  printed in the input window, will go to the log file specified in the
  2783.  IRIT.CFG configuration file. This file will be created the first time
  2784.  logfile is turned ON.
  2785.  
  2786.                                      NTH
  2787.                                      ---
  2788.  
  2789.  AnyType NTH( ListType ListObject, NumericType Index )
  2790.  
  2791.  Returns the Index (base count 1) element of the list ListObject.
  2792.  
  2793.  Example:
  2794.  
  2795.     Lst = list( a, list( b, c ), d );
  2796.     Lst2 = NTH( Lst, 2 );
  2797.  
  2798.  and now Lst2 is equal to 'list( b, c )'.
  2799.  
  2800.                                     PAUSE
  2801.                                     -----
  2802.  
  2803.  PAUSE( NumericType Flush )
  2804.  
  2805.    Waits for a keystroke. Nice to have if a temporary stop in a middle of an
  2806.  included file (see INCLUDE) is required. If Flush is TRUE, then the input
  2807.  is first flushed to guarantee that the actual stop will occur.
  2808.  
  2809.                                    PRINTF
  2810.                                    ------
  2811.  
  2812.  PRINTF( StringType CtrlStr, ListType Data )
  2813.  
  2814.  A formatted printing routine, following the concepts of the C programming
  2815.  language's printf routine. CtrlStr is a string object for which
  2816.  the following special '%' commands are supported:
  2817.  
  2818.     %d, %i, %u      Prints the numeric object as an integer or unsigned integer.
  2819.     %o, %x, %X      Prints the numeric object as an octal or hexadecimal integer.
  2820.     %e, %f, %g,     Prints the numeric object in several formats of
  2821.     %E, %F          floating point numbers.
  2822.     %s              Prints the string object as a string.
  2823.     %pe, %pf, %pg   Prints the three coordinates of the point object.
  2824.     %ve, %vf, %vg   Prints the three coordinates of the vector object.
  2825.     %Pe, %Pf, %Pg,  Prints the four coordinates of the plane object.
  2826.     %De, %Df, %Dg,  Prints the given object in IRIT's data file format.
  2827.  
  2828.  
  2829.  All the '%' commands can include any modifier that is valid in the C
  2830.  programming language printf routine, including l (long), prefix
  2831.  character(s), size, etc. The point, vector, plane, and object commands
  2832.  can also be modified in a similar way, to set the format of the
  2833.  numeric data printed.
  2834.  
  2835.  Also supported are the newline and tab using the backslash escape
  2836.  character:
  2837.  
  2838.  PRINTF("\\tThis is the char \"\\%\"\\n", nil());
  2839.  
  2840.  Backslashes should be escaped themselves as can be seen in the above example.
  2841.  Here are few more examples:
  2842.  
  2843.  PRINTF("this is a string \"%s\" and this is an integer %8d.\\n",
  2844.        list("STRING", 1987));
  2845.  PRINTF("this is a vector [%8.5lvf]\\n", list(vector(1,2,3)));
  2846.  dumplvl = 9;
  2847.  PRINTF("this is a object %8.6lDf...\\n", list(axes));
  2848.  PRINTF("this is a object %10.8lDg...\\n", list(axes));
  2849.  
  2850.  This implementation of PRINTF is somewhat different than the C programming
  2851.  language's version, because the backslash always escapes the next
  2852.  character during the processing stage of IRIT's parser. That is, the string
  2853.  
  2854.         '\\tThis is the char \"\\%\"\\n'
  2855.  
  2856.  is actually parsed by the IRIT's parser into
  2857.  
  2858.         '\tThis is the char "\%"\n'
  2859.  
  2860.  because this is the way the IRIT parser processes strings. The latter
  2861.  string is the one that PRINTF actually see.
  2862.  
  2863.                                   PROCEDURE
  2864.                                   ---------
  2865.  
  2866.  ProcName = PROCEDURE(Prm1, Prm2, ... , PrmN):LclVal1:LclVar2: ... :LclVarM:
  2867.      ProcBody;
  2868.  
  2869.  A procedure is a function that does not return a value, and therefore the
  2870.  return variable (see FUNCTION) should not be used. A procedure is
  2871.  identical to a function in every other way. See FUNCTION for more.
  2872.  
  2873.                                     SAVE
  2874.                                     ----
  2875.  
  2876.  SAVE( StringType FileName, AnyType Object )
  2877.  
  2878.    Saves the provided Object in the specified file name FileName.
  2879.  No extension type is needed (ignored if specified), and ".dat" is always
  2880.  used. Object can be any object type, including list, in which structure
  2881.  is saved recursively. See also LOAD. If a display device is actively running
  2882.  at the time SAVE is invoked, its transformation matrix will be saved with the
  2883.  same name but with extension type of ".mat" instead of ".dat".
  2884.  
  2885.    Under unix, files will be saved compressed if the given file name has
  2886.  a postfix of ".Z". The unix system's "compress" will be invoked via a pipe
  2887.  for that purpose.
  2888.  
  2889.                                     SNOC
  2890.                                     ----
  2891.  
  2892.  SNOC( AnyType Object, ListType ListObject )
  2893.  
  2894.    Similar to the lisp cons operator but puts the new Object in the
  2895.  end of the list ListObject instead of the beginning, in place.
  2896.  
  2897.  Example:
  2898.  
  2899.     Lst = list( axes );
  2900.     SNOC( Srf, Lst );
  2901.  
  2902.  and now Lst is equal to the list 'list( axes, Srf )'.
  2903.  
  2904.                                    SYSTEM
  2905.                                    ------
  2906.  
  2907.  SYSTEM( StringType Command )
  2908.  
  2909.    Executes a system command Command. For example,
  2910.  
  2911.     SYSTEM( "ls -l" );
  2912.  
  2913.                                     TIME
  2914.                                     ----
  2915.  
  2916.  TIME( NumericType Reset )
  2917.  
  2918.    Returns the time in seconds from the last time TIME was called with
  2919.  Reset TRUE. This time is CPU time if such support is available
  2920.  from the system (times function), and is real time otherwise (time
  2921.  function).
  2922.    The time is automatically reset at the beginning of the execution of this
  2923.  program.
  2924.  
  2925.  Example:
  2926.  
  2927.     Dummy = TIME( TRUE );
  2928.       .
  2929.       .
  2930.       .
  2931.     TIME( FALSE );
  2932.  
  2933.  prints the time in seconds between the above two time function calls.
  2934.  
  2935.                                    VARLIST
  2936.                                    -------
  2937.  
  2938.  VARLIST()
  2939.  
  2940.    List all the currently defined objects in the system.
  2941.  
  2942.                                    VECTOR
  2943.                                    ------
  2944.  
  2945.  VectorType VECTOR( NumericType X, NumericType Y, NumericType Z )
  2946.  
  2947.    Creates a vector type object, using the three provided NumericType scalars.
  2948.  
  2949.                                     VIEW
  2950.                                     ----
  2951.  
  2952.  VIEW( GeometricTreeType Object, NumericType ClearWindow )
  2953.  
  2954.    Displays the (geometric) object(s) as given in Object.
  2955.  
  2956.    If ClearWindow is non-zero (see TRUE/FALSE and ON/OFF) the window is
  2957.  first cleared (before drawing the objects).
  2958.  
  2959.  Example:
  2960.  
  2961.     VIEW( Axes, FALSE );
  2962.  
  2963.  displays the predefined object Axes in the viewing window on top of
  2964.  what is drawn already.
  2965.  
  2966.  In version 4.0, this function is emulated (see iritinit.irt) using the
  2967.  VIEWOBJ function. In order to use the current viewing matrix, VIEW_MAT
  2968.  should be provided as an additional parameter. For example,
  2969.  
  2970.     VIEW( list( view_mat, Obj ), TRUE );
  2971.  
  2972.  However, since VIEW is a user defined function, the following will not
  2973.  use VIEW_MAT as one would expect:
  2974.  
  2975.     VIEW( view_mat, TRUE );
  2976.  
  2977.  because VIEW_MAT will be renamed inside the VIEW user defined function to
  2978.  a local (to the user defined function) variable.
  2979.  
  2980.  In iritinit.irt one can find several other useful VIEW related functions:
  2981.  
  2982.     VIEWCLEAR       Clears all data displayed on the display device.
  2983.     VIEWREMOVE      Removes the object specified by name from display.
  2984.     VIEWDISC        Disconnects from display device (which is still running)
  2985.                     while allowing IRIT to connect to a new device.
  2986.     VIEWEXIT        Forces the display device to exit.
  2987.     VIEWSAVE        Request sdisplay device to save transformation matrix.
  2988.     BEEP            An emulation of the BEEP command of versions prior to 4.0.
  2989.     VIEWSTATE       Allows to change the state of the display device.
  2990.  
  2991.  
  2992.    For the above VIEW related functions, only VIEWREMOVE, VIEWSAVE, and
  2993.  VIEWSTATE require a parameter, which is the file name and view state
  2994.  respectively. The view state can be one of several commands. See the
  2995.  display device section for more.
  2996.  
  2997.  Examples:
  2998.  
  2999.     VIEWCLEAR();
  3000.     VIEW( axes, off );
  3001.     VIEWSTATE( "LngrVecs" );
  3002.     VIEWSTATE( "DrawSolid" );
  3003.     VIEWSAVE( "matrix1" );
  3004.     VIEWREMOVE( "axes" );
  3005.     VIEWDISC();
  3006.  
  3007.                                    VIEWOBJ
  3008.                                    -------
  3009.  
  3010.  VIEWOBJ( GeometricTreeType Object )
  3011.  
  3012.    Displays the (geometric) object(s) as given in Object.
  3013.  Object may be any GeometricType or a list of other
  3014.  GeometricTypes nested to an arbitrary level.
  3015.  
  3016.    Unlike IRIT versions prior to 4.0, VIEW_MAT is not explicitly used
  3017.  as the transformation matrix. In order to display with a VIEW_MAT view,
  3018.  VIEW_MAT should be listed as an argument (in that exact name) to
  3019.  VIEWOBJ. Same is true for the perspective matrix PRSP_MAT.
  3020.  
  3021.  Example:
  3022.  
  3023.     VIEWOBJ( list( view_mat, Axes ), FALSE );
  3024.  
  3025.  displays the predefined object Axes in the viewing window using the
  3026.  viewing matrix VIEW_MAT.
  3027.  
  3028.                               System variables
  3029.                               ----------------
  3030.  
  3031.  System variables are predefined objects in the system. Any time IRIT is
  3032.  executed, these variable are automatically defined and set to values which
  3033.  are sometimes machine dependent. These are regular objects in any other
  3034.  sense, including the ability to delete or overwrite them. One can modify,
  3035.  delete, or introduce other objects using the IRITINIT.IRT file.
  3036.  
  3037.                                     AXES
  3038.                                     ----
  3039.    Predefined polyline object (PolylineType) that describes the XYZ axes.
  3040.  
  3041.                                   COPLANAR
  3042.                                   --------
  3043.    Predefined Boolean object (NumericType). If TRUE the polygonal Boolean
  3044.  operations will support coplanar faces but is somewhat slower.
  3045.  Default is FALSE.
  3046.  
  3047.                                   DRAWCTLPT
  3048.                                   ---------
  3049.    Predefined Boolean variable (NumericType) that controls whether curves'
  3050.  control polygons and surfaces' control meshes are drawn (TRUE) or not
  3051.  (FALSE). Default is FALSE.
  3052.  
  3053.                                    DUMPLVL
  3054.                                    -------
  3055.    Content of objects assigned to variables can be displayed by executing the
  3056.  command 'ObjName;' where ObjName is the name of the object. This variable
  3057.  (NumericType) controls the way the data are dumped as follows:
  3058.  
  3059.  
  3060.     DumpLvl >= 0         Only object names/types are printed.
  3061.     DumpLvl >= 1         Non-geometric object values are dumped.
  3062.     DumpLvl >= 2         Curves and Surfaces are dumped.
  3063.     DumpLvl >= 3         Polygons/lines are dumped.
  3064.     DumpLvl >= 4         List objects are traversed recursively.
  3065.  
  3066.  Default value is 1.
  3067.  
  3068.                                    ECHOSRC
  3069.                                    -------
  3070.    Predefined Boolean variable (NumericType) controlling echoing of
  3071.  interpreted commands to screen (TRUE) or not (FALSE). Default value is TRUE.
  3072.  
  3073.                                   FLAT4PLY
  3074.                                   --------
  3075.    Predefined Boolean object (NumericType) that controls the way almost flat
  3076.  surface patches are converted to polygons: four polygons (TRUE) or only
  3077.  two polygons (FALSE). Default value is FALSE.
  3078.  
  3079.                                   INTERCRV
  3080.                                   --------
  3081.    Predefined numeric object (NumericType) that if TRUE the Boolean geometry
  3082.  operators return the intersection curves instead of the result model.
  3083.  Default value is FALSE.
  3084.  
  3085.                                    MACHINE
  3086.                                    -------
  3087.    Predefined numeric object (NumericType) holding the machine type as one of
  3088.  the following constants: MSDOS, SGI, HP, SUN, APOLLO, UNIX, IBMOS2, IBMNT,
  3089.  and AMIGA.
  3090.  
  3091.                                   POLYSORT
  3092.                                   --------
  3093.    Predefined numeric object (NumericType) that determines the directional
  3094.  axis along which the polygons are sorted during Boolean operations. Default is
  3095.  the x axis or 0. Set to 1 for y sorting. or to 2 for z sorting.
  3096.  
  3097.                                   PRSP_MAT
  3098.                                   --------
  3099.    Predefined matrix object (MatrixType) to hold the perspective matrix
  3100.  used/set by VIEW and/or INTERACT commands. See also VIEW_MAT.
  3101.  
  3102.                                  RESOLUTION
  3103.                                  ----------
  3104.    Predefined numeric object (NumericType) that sets the accuracy of the
  3105.  polygonal primitive geometric objects and the approximation of curves and
  3106.  surfaces. Holds the number of divisions a circle is divided into (with
  3107.  minimum value of 4). If, for example, RESOLUTION is set to 6, then a
  3108.  generated CONE will effectively be a six-sided pyramid.
  3109.    Also controls the fineness of freeform curves and surfaces when they are
  3110.  approximated as piecewise linear polylines, and the fineness of freeform
  3111.  surfaces when they are approximated as polygons.
  3112.  
  3113.                                   VIEW_MAT
  3114.                                   --------
  3115.    Predefined matrix object (MatrixType) to hold the viewing matrix used/set
  3116.  by VIEW and/or INTERACT commands. See also PRSP_MAT.
  3117.  
  3118.                               System constants
  3119.                               ----------------
  3120.  
  3121.  The following constants are used by the various functions of the system to
  3122.  signal certain conditions. Internally, they are represented numerically,
  3123.  although, in general, their exact value is unimportant and may be changed
  3124.  in future versions. In the rare circumstance that  you need to know their
  3125.  values, simply type the constant as an expression.
  3126.  
  3127.  Example:
  3128.  
  3129.     MAGENTA;
  3130.  
  3131.                                     AMIGA
  3132.                                     -----
  3133.  A constant designating an AMIGA system, in the MACHINE variable.
  3134.  
  3135.                                    APOLLO
  3136.                                    ------
  3137.  A constant designating an APOLLO system, in the MACHINE variable.
  3138.  
  3139.                                     BLACK
  3140.                                     -----
  3141.  A constant defining a BLACK color.
  3142.  
  3143.                                     BLUE
  3144.                                     ----
  3145.  A constant defining a BLUE color.
  3146.  
  3147.                                      COL
  3148.                                      ---
  3149.  A constant defining the COLumn direction of a surface mesh.
  3150.  
  3151.                                  CTLPT_TYPE
  3152.                                  ----------
  3153.  A constant defining an object of type control point.
  3154.  
  3155.                                  CURVE_TYPE
  3156.                                  ----------
  3157.  A constant defining an object of type curve.
  3158.  
  3159.                                     CYAN
  3160.                                     ----
  3161.  A constant defining a CYAN color.
  3162.  
  3163.                                      E1
  3164.                                      --
  3165.  A constant defining an E1 (X only coordinate) control point type.
  3166.  
  3167.                                      E2
  3168.                                      --
  3169.  A constant defining an E2 (X and Y coordinates) control point type.
  3170.  
  3171.                                      E3
  3172.                                      --
  3173.  A constant defining an E3 (X, Y and Z coordinates) control point type.
  3174.  
  3175.                                      E4
  3176.                                      --
  3177.  A constant defining an E4 control point type.
  3178.  
  3179.                                      E5
  3180.                                      --
  3181.  A constant defining an E5 control point type.
  3182.  
  3183.                                     FALSE
  3184.                                     -----
  3185.  A zero constant. May be used as Boolean operand.
  3186.  
  3187.                                     GREEN
  3188.                                     -----
  3189.  A constant defining a GREEN color.
  3190.  
  3191.                                      HP
  3192.                                      --
  3193.  A constant designating an HP system, in the MACHINE variable.
  3194.  
  3195.                                     IBMOS
  3196.                                     -----
  3197.  A constant designating an IBM system running under OS2, in the MACHINE
  3198.  variable.
  3199.  
  3200.                                     IBMNT
  3201.                                     -----
  3202.  A constant designating an IBM system running under Windows NT, in the MACHINE
  3203.  variable.
  3204.  
  3205.                                   KV_FLOAT
  3206.                                   --------
  3207.  A constant defining a floating end condition uniformly spaced knot vector.
  3208.  
  3209.                                    KV_OPEN
  3210.                                    -------
  3211.  A constant defining an open end condition uniformly spaced knot vector.
  3212.  
  3213.                                    MAGENTA
  3214.                                    -------
  3215.  A constant defining a MAGENTA color.
  3216.  
  3217.                                  MATRIX_TYPE
  3218.                                  -----------
  3219.  A constant defining an object of type matrix.
  3220.  
  3221.                                     MSDOS
  3222.                                     -----
  3223.  A constant designating an MSDOS system, in the MACHINE variable.
  3224.  
  3225.                                 NUMERIC_TYPE
  3226.                                 ------------
  3227.  A constant defining an object of type numeric.
  3228.  
  3229.                                      OFF
  3230.                                      ---
  3231.  Synonym of FALSE.
  3232.  
  3233.                                      ON
  3234.                                      --
  3235.  Synonym for TRUE.
  3236.  
  3237.                                      P2
  3238.                                      --
  3239.  A constant defining a P1 (X and W coordinates) rational control point
  3240.  type.
  3241.  
  3242.                                      P2
  3243.                                      --
  3244.  A constant defining a P2 (X, Y and W coordinates) rational control point
  3245.  type.
  3246.  
  3247.                                      P3
  3248.                                      --
  3249.  A constant defining a P3 (X, Y, Z and W coordinates) rational control
  3250.  point type.
  3251.  
  3252.                                      P4
  3253.                                      --
  3254.  A constant defining a P4 rational control
  3255.  point type.
  3256.  
  3257.                                      P5
  3258.                                      --
  3259.  A constant defining a P5 rational control
  3260.  point type.
  3261.  
  3262.                                      PI
  3263.                                      --
  3264.  The constant of 3.141592...
  3265.  
  3266.                                  PLANE_TYPE
  3267.                                  ----------
  3268.  A constant defining an object of type plane.
  3269.  
  3270.                                  POINT_TYPE
  3271.                                  ----------
  3272.  A constant defining an object of type point.
  3273.  
  3274.                                   POLY_TYPE
  3275.                                   ---------
  3276.  A constant defining an object of type poly.
  3277.  
  3278.                                      RED
  3279.                                      ---
  3280.  A constant defining a RED color.
  3281.  
  3282.                                      ROW
  3283.                                      ---
  3284.   A constant defining the ROW direction of a surface mesh.
  3285.  
  3286.                                      SGI
  3287.                                      ---
  3288.  A constant designating an SGI system, in the MACHINE variable.
  3289.  
  3290.                                  STRING_TYPE
  3291.                                  -----------
  3292.  A constant defining an object of type string.
  3293.  
  3294.                                 SURFACE_TYPE
  3295.                                 ------------
  3296.  A constant defining an object of type surface.
  3297.  
  3298.                                      SUN
  3299.                                      ---
  3300.  A constant designating a SUN system, in the MACHINE variable.
  3301.  
  3302.                                     TRUE
  3303.                                     ----
  3304.  A non zero constant. May be used as Boolean operand.
  3305.  
  3306.                                     UNIX
  3307.                                     ----
  3308.  A constant designating a generic UNIX system, in the MACHINE variable.
  3309.  
  3310.                                  VECTOR_TYPE
  3311.                                  -----------
  3312.  A constant defining an object of type vector.
  3313.  
  3314.                                     WHITE
  3315.                                     -----
  3316.  A constant defining a WHITE color.
  3317.  
  3318.                                    YELLOW
  3319.                                    ------
  3320.  A constant defining a YELLOW color.
  3321.  
  3322.  
  3323.                                Display devices
  3324.                                ---------------
  3325.  
  3326.  The following display device drivers are available,
  3327.  
  3328.     Device Name      Invocation       Environment  
  3329.                                                    
  3330.     xgldrvs          xgldrvs -s-      SGI 4D GL regular driver.
  3331.     xgladap          xgladap -s-      SGI 4D GL adaptive isocurve experminal driver.
  3332.     x11drvs          xgldrvs -s-      X11 driver.  
  3333.     wntdrvs          wntdrvs -s-      IBM PC Windows NT driver.
  3334.     os2drvs          os2drvs -s-      IBM PC OS2 2.x driver.
  3335.     amidrvs          amidrvs -s-      AmigaDOS 2.04+ driver.
  3336.     nuldrvs          nuldrvs -s- [-d] [-D]   A device to print the object stream to stdout.
  3337.  
  3338.  
  3339.  All display devices are clients communicating with the server (IRIT)
  3340.  using IPC (inter process communication). On Unix and Window NT sockets are
  3341.  used. A Windows NT client can talk to a server (IRIT) on a unix host if
  3342.  hooked to the same netwrok. On OS2 pipes are used, and both the client and
  3343.  server must run on the same machine. On AmigaDOS exec messages are used,
  3344.  and both the client and server must run on the same machine.
  3345.  
  3346.    The server (IRIT) will automatically start a client display device
  3347.  if the IRIT_DISPLAY environment variable is set to the name and options of
  3348.  the display device to run. For example:
  3349.  
  3350.     setenv IRIT_DISPLAY xgldrvs -s-
  3351.  
  3352.    The display device must be in a directory that is in the path
  3353.  environment variable. Most display devices require the '-s-' flags to run
  3354.  in a non-standalone mode, or a client-server mode. Most drivers can also
  3355.  be used to display data in a standalone mode (i.e., no server). For
  3356.  example:
  3357.  
  3358.     xgldrvs -s solid1.dat irit.mat
  3359.  
  3360.     Effectively, all the display devices are also data display programs
  3361.  (poly3d, which was the display program prior to version 4.0, is retired
  3362.  in 4.0). Therefore some functionality is not always as expected. For
  3363.  example, the quit button will always force the display device to quit,
  3364.  even if poped up from IRIT, but will not cause IRIT to
  3365.  quit as might logically expected. In fact, the next time IRIT will
  3366.  try to communicate with the display device, it will find the broken
  3367.  connection and will start up a new display device.
  3368.  
  3369.     All display devices recognize all the command line flags and all the
  3370.  configuration options in a configuration file, as described below. The display
  3371.  devices will make attemps to honor the requests, to the best of their ability.
  3372.     For example, only xgldrvs can render shaded models, and so only it will
  3373.  honor a DrawSolid configuration options.
  3374.  
  3375.                             Command Line Options
  3376.                             --------------------
  3377.  
  3378.  ???drvs [-s] [-u] [-n] [-N] [-i] [-c] [-m] [-I #IsoLines] [-S #SampPerCrv]
  3379.          [-f FineNess] [-l LineWidth] [-d] [-D] [-L NormalLen] [-4]
  3380.          [-b BackGround] [-M] [-P] [-z] DFiles 
  3381.  
  3382.   -s: Runs the driver in a Standalone mode. Otherwise, the driver will
  3383.         attempt to communicate with the IRIT server.
  3384.   -u: Forces a Unit matrix. That is, input data are not
  3385.         transformed at all.
  3386.   -n: Draws normals of vertices.
  3387.   -N: Draws normals of polygons.
  3388.   -i: Draws internal edges (created by IRIT) - default is not to
  3389.         display them, and this option will force displaying them as well.
  3390.   -c: Sets depth cueing on. Drawings that are closer to the viewer will
  3391.         be drawn in more intense color.
  3392.   -m: Provides some more information on the data file(s) parsed.
  3393.   -I #IsoLines: Specifies number of isolines per surface, per direction.
  3394.   -S #SampPerCrv: Specifies the log based 2 of number of samples per
  3395.         (iso)curve.
  3396.   -f FineNess: Controls the fineness of the surface to polygon subdivision.
  3397.         This number is log based 2 of roughly the number of subdivisions of
  3398.         the surface in each axis.
  3399.   -l LineWidth: Sets the linewidth, in pixels. Default is one pixel wide.
  3400.   -d: Debug objects. Prints to stderr all objects read from communcation
  3401.         port with the server IRIT. 
  3402.   -D: Debug input. Prints to stderr all characters read from communcation
  3403.         port with the server IRIT. Lowest level of communication.
  3404.   -L NormalLen: Sets the length of the drawn normals in thousandths of
  3405.         a unit.
  3406.   -4: Forces four polygons per almost flat region in the surface to
  3407.         polygon conversion. Otherwise two polygons only.
  3408.   -b BackGround: Sets the background color as three RGB integers in the
  3409.         range of 0 to 255.
  3410.   -M: Draw control mesh/polygon of curves and surfaces, as well.
  3411.   -P: Draws curves and surfaces (surfaces are drawn using a set of
  3412.         isocurves, see -I, or polygons, see -f).
  3413.   -z: Prints version number and current defaults.
  3414.  
  3415.                             Configuration Options
  3416.                             ---------------------
  3417.  
  3418.  The configuration file is read before the command line options are
  3419.  processed. Therefore, all options in this section can be overriden
  3420.  by the appropriate command line option, if any.
  3421.  
  3422.   TransPrefPos: Preferred location (Xmin, YMin, Xmax, Ymax) of the
  3423.         transformation window.
  3424.   ViewPrefPos: Preferred location (Xmin, YMin, Xmax, Ymax) of the
  3425.         viewing window.
  3426.   BackGround: Background color. Same as '-b'.
  3427.   Internal: Draws internal edges. Same as '-i'.
  3428.   DrawVNormal: Draws normals of vertices. Same as '-n'.
  3429.   DrawPNormal: Draws normals of polygons. Same as '-n'.
  3430.   MoreVerbose: Provides some more information on the data file(s)
  3431.         parsed. Same as '-m'.
  3432.   UnitMatrix: Forces a Unit matrix. That is, input data are not
  3433.         transformed at all. Same as '-u'.
  3434.   DrawSolid: Requests a shaded surface rendering, as opposed to isocurve
  3435.         surface representation.
  3436.   DoubleBuffer: Requests drawing using a double buffer, if any.
  3437.   NumOfIsolines:  Specifies number of isolines per surface, per
  3438.         direction. Same as '-I'.
  3439.   SamplesPerCurve: Specifies the log based 2 of number of samples per
  3440.         (iso)curve. Same as '-S'.
  3441.   LineWidth: Sets the linewidth, in pixels. Default is one pixel
  3442.        wide. Same as '-l'
  3443.   AdapIsoDir: Selects the direction of the adaptive isoline
  3444.         rendering.
  3445.   FineNess: Controls the fineness of the surface to polygon subdivision.
  3446.         This number is log based 2 of roughly the number of subdivisions of
  3447.         the surface in each axis. Same as '-f'.
  3448.   DepthCue: Set depth cueing on. Drawings that are closer to the
  3449.         viewer will be drawn in more intense color. Same as '-c'.
  3450.   FourPerFlat: Forces four polygons per almost flat region in the
  3451.         surface to polygon conversion. Otherwise two polygons only. Same as
  3452.         '-4'.
  3453.   AntiAlias: Request the drawing of anti aliased lines.
  3454.   DrawSurfaceMesh: Draws control mesh/polygon of curves and surfaces,
  3455.         as well. Same as '-M'.
  3456.   DrawSurfacePoly: Draws curves and surfaces (surfaces are drawn using
  3457.         a set of isocurves, see -I, or polygons, see -f). Same as '-P'.
  3458.   StandAlone: Runs the driver in a Stand alone mode. Otherwise, the
  3459.         driver will attempt to communicate with the IRIT server. Same
  3460.         as '-s'.
  3461.   TransMode: Selects between object space transformations and screen
  3462.         space transformation.
  3463.   ViewMode: Selects between perspective and orthographic views.
  3464.   NormalLength: Sets the length of the drawn normals in thousandths of
  3465.         a unit. Same as '-L'.
  3466.   DebugObjects: Debug objects. Prints to stderr all objects read
  3467.         from the communcation port with the server IRIT. Same as '-d'.
  3468.   DebugEchoInput: Debug input. Prints to stderr all characters read
  3469.         from the communcation port with the server IRIT. Lowest level of
  3470.         communications.
  3471.  
  3472.                            Interactive mode setup
  3473.                            ----------------------
  3474.  
  3475.    Commands that affect the status of the display device can also be sent
  3476.  via the communication port with the IRIT server. The following commands
  3477.  are recognized,
  3478.  
  3479.     CLEAR            Clears the display area. All objects displayed are deleted.
  3480.     DCLEAR           Delayed clear. Same as CLEAR but delayed until the next
  3481.    
  3482.                  object is sent from the server. Useful for animation.
  3483.     DISCONNECT       Closes connection with the server, but does not quit.
  3484.     EXIT             Closes connection with the server and quits.
  3485.     MSAVE NAME       Saves the transformation matrix file by the name NAME.
  3486.     BEEP             Makes some sound.
  3487.     STATE COMMAND    Changes the state of the display device. See below.
  3488.  
  3489.    The following commands are valid for the STATE COMMAND above,
  3490.  
  3491.     MoreSense:        More sensitive mouse control.
  3492.     LessSense:        Less sensitive mouse control.
  3493.     ScrnObject:       Toggle screen/object transformation mode.
  3494.     PerspOrtho:       Toggles perspective/orthographic trans. mode.
  3495.     DepthCue:         Toggles depth cueing drawing.
  3496.     DrawSolid:        Toggles isocurve/shaded solid drawing.
  3497.     DblBuffer:        Toggles single/double buffer mode.
  3498.     AntiAlias:        Toggles anti aliased lines.
  3499.     DrawIntrnl:       Toggles drawing of internal lines.
  3500.     DrawVNrml:        Toggles drawing of normals of vertices.
  3501.     DrawPNrml:        Toggles drawing of normals of polygons.
  3502.     DSrfMesh:         Toggles drawing of control meshes/polygons.
  3503.     DSrfPoly:         Toggles drawing of curves/surfaces.
  3504.     4PerFlat:         Toggles 2/4 polygons per flat surface regions.
  3505.     MoreIso:          Doubles the number of isolines in a surface.
  3506.     LessIso:          Halves the number of isolines in a surface.
  3507.     FinrAprx:         Doubles the number of samples per curve.
  3508.     CrsrAprx:         Halves the number of samples per curve.
  3509.     LngrVecs:         Doubles the length of displayed normal vectors.
  3510.     ShrtrVecs:        Halves the length of displayed normal vectors.
  3511.     WiderLns:         Doubles the width of the drawn lines.
  3512.     NarrwLns:         Halves the width of the drawn lines.
  3513.     FinrAdapIso:      Doubles the number of adaptive isocurves.
  3514.     CrsrAdapIso:      Halves the number of adaptive isocurves.
  3515.     FinerRld:         Doubles the number of ruled surfaces in adaptive isocurves.
  3516.     CrsrRld:          Halves the number of ruled surfaces in adaptive isocurves.
  3517.     RuledSrfApx:      Toggles ruled surface approximation in adaptive isocurves.
  3518.     AdapIsoDir:       Toggles the row/col direction of adaptive isocurves.
  3519.     Front:            Selects a front view.
  3520.     Side:             Selects a side view.
  3521.     Top:              Selects a top view.
  3522.     Isometry:         Selects an isometric view.
  3523.  
  3524.  Obviously not all state options are valid for all drivers.
  3525.    The IRIT server defines in iritinit.irt several user-defined
  3526.  functions that exercise some of the above state commands, such as
  3527.  VIEWSTATE and VIEWSAVE.
  3528.  
  3529.    In addition to state modification via communication with the IRIT
  3530.  server, modes can be interactively modified on most of the display devices
  3531.  using a pop-up menu that is activated using the right button in the
  3532.  transformation window}.
  3533.    This pop up menu is somewhat different in different drivers, but its
  3534.  entries closely follow the entries of the above state command table.
  3535.  
  3536.  
  3537.                           Utilities - General Usage
  3538.                           -------------------------
  3539.  
  3540.    The IRIT solid modeler is accompanied by quite a few utilities. They
  3541.  can be subdivided into two major groups. The first includes auxiliary tools
  3542.  such as illustrt and poly3d-h. The second includes filters such as irit2ray
  3543.  and irit2ps.
  3544.  
  3545.    All these tools operate on input files, and most of the time produce
  3546.  data files. In all utilities that read files, the dash ('-') can be used
  3547.  to read stdin.
  3548.  
  3549.  Example:
  3550.  
  3551.  poly3d-h solid1.dat | irit2ps - > solid1.ps
  3552.  
  3553.    All the utilities have command line options. If an option is set by a '-x'
  3554.  then '-x-' resets the option. The command line options overwrite the settings
  3555.  in config files, and the reset option is useful for cases where the option
  3556.  is set by default, in the configuration file.
  3557.  
  3558.    All utilities can read a sequence of data files. However, the last
  3559.  transformation matrices found (VIEW_MAT and PRSP_MAT) are actually used.
  3560.  
  3561.  Example:
  3562.  
  3563.  poly3d-h solid1.dat | x11drvs solid1.dat - solid1.mat 
  3564.  
  3565.  x11drvs will display the original solid1.dat file with its hidden version,
  3566.  as computed by poly3d-h, all with the solid1.mat, ignoring all other matrices
  3567.  in the data stream.
  3568.  
  3569.  Under unix, compressed files with a postfix ".Z" will be automatically
  3570.  uncompressed on read and write. The following is legal under unix,
  3571.  
  3572.  poly3d-h solid1.dat.Z | x11drvs solid1.dat.Z - solid1.mat
  3573.  
  3574.  where solid1.dat.Z was saved from within IRIT using the command
  3575.  
  3576.  save( "solid1.dat.Z", solid1 );
  3577.  
  3578.  or similar. The unix system's "compress" and "zcat" are used for the purpose
  3579.  of (un)compressing the data via pipes. See also SAVE and LOAD.
  3580.  
  3581.  
  3582.                        poly3d - A Data Display Program
  3583.                        -------------------------------
  3584.  
  3585.  This program has been retired. The display devices should be used instead.
  3586.  See the display drivers section.
  3587.  
  3588.  
  3589.                    poly3d-h - Hidden Line Removing Program
  3590.                    ---------------------------------------
  3591.  
  3592.  
  3593.  
  3594.                                 Introduction
  3595.                                 ------------
  3596.  
  3597.     poly3d-h is a program to remove hidden lines from a given polygonal model.
  3598.  Freeform objects are preprocessed into polygons with controlled fineness.
  3599.  
  3600.     The program performs 4 passes over the input:
  3601.  
  3602.  1. Preprocesses and maps all polygons in a scene, and sorts them.
  3603.  
  3604.  2. Generates edges out of the polygonal model and sorts them (preprocessing
  3605.     for the scan line algorithm) into buckets.
  3606.  
  3607.  3. Intersects edges, and splits edges with non-homogeneous visibility (the
  3608.     scan line algorithm).
  3609.  
  3610.  4. Applies a visibility test of each edge.
  3611.  
  3612.         This program can handle CONVEX polygons only. From IRIT one can
  3613.  ensure that a model consists of convex polygons only using the CONVEX command:
  3614.   CnvxObj = convex( Obj );
  3615.  just before saving it into a file. Surfaces are always decomposed into
  3616.  triangles.
  3617.  
  3618.     poly3d-h output is in the form of polylines. It is a regular IRIT data
  3619.  file that can be viewed using any of the display devices, for example.
  3620.  
  3621.                             Command line options
  3622.                             --------------------
  3623.  
  3624.  poly3d-h [-b] [-m] [-i] [-e #Edges] [-f FineNess] [-H] [-4] [-q] [-z] [-c]
  3625.                                            [-o OutName] DFiles > OutFile
  3626.  
  3627.   -b: BackFacing - if an object is closed (such as most models created by
  3628.        IRIT), back facing polygons can be deleted, therefore speeding up
  3629.        the process by at least a factor of two.
  3630.   -m: More - provides some more information on the data file(s) parsed.
  3631.   -i: Internal edges (created by IRIT) - default is not to
  3632.        display them, and this option will force displaying them as well.
  3633.   -e n: Number of edges to use from each given polygon (default all).
  3634.        Handy as '-e 1 -4' for freeform data.
  3635.   -f FineNess: Controls the fineness of the surface to polygon subdivision.
  3636.        This number is log based 2 of roughly the number of subdivisions of
  3637.        the surface in each axis.
  3638.   -H: Dumps both visible lines and hidden lines as separated objects.
  3639.        Hidden lines will be dumped using a different (dimmer) color and (a
  3640.        narrower) line width.
  3641.   -4: Forces four polygons per almost flat region in the surface to
  3642.        polygon conversion. Otherwise two polygons only.
  3643.   -q: Quiet mode. No printing aside from fatal errors. Disables -m.
  3644.   -o OutName: Name of output file. Default is stdout.
  3645.   -z: Prints version number and current defaults.
  3646.   -c: Clips data to screen (default). If disabled ('-c-'), data
  3647.        outside the view screen ([-1, 1] in x and y) are also processed.
  3648.  
  3649.    Some of the options may be turned on in poly3d-h.cfg. They can be then
  3650.  turned off in the command line as '-?-'.
  3651.  
  3652.                                 Configuration
  3653.                                 -------------
  3654.  
  3655.    The program can be configured using a configuration file named poly3d-h.cfg.
  3656.    This is a plain ASCII file you can edit directly and set the parameters
  3657.  according to the comments there. 'poly3d-h -z' will display the current
  3658.  configuration as read from the configuration file.
  3659.  
  3660.    The configuration file is searched in the directory specified by the
  3661.  IRIT_PATH environment variable. For example,
  3662.  'setenv IRIT_PATH /u/gershon/irit/bin/'.
  3663.    If the IRIT_PATH variable is not set, the current directory is searched.
  3664.  
  3665.                                     Usage
  3666.                                     -----
  3667.  
  3668.    As this program is not interactive, usage is quite simple, and the only
  3669.  control available is using the command line options.
  3670.  
  3671.  
  3672.                  poly3d-r - A Simple Data Rendering Program
  3673.                  ------------------------------------------
  3674.  
  3675.  
  3676.                                 Introduction
  3677.                                 ------------
  3678.  
  3679.  poly3d-r is a simple rendering program for data files created by the IRIT
  3680.  solid modeler. poly3d-r generates GIF images with 8 bits per pixel. As a
  3681.  result, rendered images are of medium quality. Although reasonably fast,
  3682.  one should consider one of several raytracing public domain programs
  3683.  available (such as RAYSHADE, for which irit2ray can generate data) for
  3684.  high quality images.
  3685.  
  3686.    poly3d-r uses cosine shading approximation, and flat/Gouraud interpolation.
  3687.  The program performs 4 passes over the input:
  3688.  
  3689.  1. Processes the input (parsing.)
  3690.  
  3691.  2. Prepares the polygons by sorting them by their Y after mapping then into
  3692.     screen space.
  3693.  
  3694.  3. Evaluates colors for vertices (using polygon normals if flat shading, or
  3695.     by vertex normals for Gouraud shading).
  3696.  
  3697.  4. Scans the data in a scan line fashion and dumps out the image.
  3698.  
  3699.         This program can handle CONVEX polygons only. From IRIT one can
  3700.  ensure that a model consists of convex polygons only using the CONVEX command:
  3701.   CnvxObj = convex( Obj );
  3702.  just before saving it into a file. Surfaces are always decomposed into
  3703.  triangles.
  3704.  
  3705.                             Command line options
  3706.                             --------------------
  3707.  
  3708.  poly3d-r [-a Ambient] [-c N] [-l X Y Z] [-2] [-m] [-s Xsize Ysize]
  3709.        [-S SubSample] [-g] [-b] [-M Mask] [-f FineNess] [-z] DFiles > Image.gif
  3710.  
  3711.   -a Ambient: Sets the ambient intensity (must be between 0.0 and 1.0).
  3712.   -c N: number of bits per pixel N (must be between 1 and 8 bits).
  3713.   -l X Y Z: specifies the light source normal direction. This vector
  3714.      does not have to be a unit vector. Only one light source is supported.
  3715.   -2 : Forces emulation of 2 light sources at opposite directions as
  3716.      selected via [-l]. This may be useful for models that have no plane
  3717.      specified (i.e., the models has no PLANE attribute for their polygons),
  3718.      as the program guesses the equation from the points themselves, and
  3719.      which can be in the opposite of the desired direction.
  3720.   -m: More - provides some more information on the data file(s) parsed.
  3721.   -s Xsize Ysize: specifies image dimensions. As the models created by IRIT
  3722.      are mapped to a unit domain (X in [-1..1], Y in [-1..1]) by the
  3723.      viewing matrix, objects must be scaled up. The scaling up factor is
  3724.      MIN(Xsize, Ysize), which guarantees none of the original image will be
  3725.      clipped.
  3726.   -b: Purges back facing polygons. If the scene contains closed objects
  3727.      (such as the ones usually created by IRIT), the back facing
  3728.      polygons can be deleted. This would not change the image, but will
  3729.      speed up the process by about %15. Using this option for incomplete
  3730.      boundary objects and/or objects with polygons with no PLANE specified
  3731.      will almost definitely create an incorrect image.
  3732.   -g: Use Gouraud shading interpolation (flat shading is used by default).
  3733.      This is somewhat slower, but creates nicer results.
  3734.   -S SubSample: subsamples, and uses a box filter to low-pass filter the
  3735.      image, using a grid size of SubSample by SubSample.
  3736.      This obviously makes things slower, but guess what - it looks much better.
  3737.   -M Mask: Creates a second GIF file named Mask that is a binary image set
  3738.      to 1 at any pixel covered by one of the objects, and 0 otherwise. As a
  3739.      color of an object can become equal to the background at some point,
  3740.      there is no way to find whether a pixel is representing the background
  3741.      or an object in the background color. The Mask can be used instead. This
  3742.      Mask can be used when combining images (such as the gifcomp utility in
  3743.      gif_lib). This image is a binary alpha channel.
  3744.   -f FineNess: Controls the fineness of the surface to polygon subdivision.
  3745.      This number is log based 2 of roughly the number of subdivisions of
  3746.      the surface in each axis (see cagd_lib for more).
  3747.   -z: Prints version number and current defaults.
  3748.  
  3749.    The image is dumped to stdout as a GIF image which can be redirected to a
  3750.  file or piped to any program that reads GIF images from stdin.
  3751.  
  3752.    Some of the options may be turned on in poly3d-r.cfg. They can be then
  3753.  turned off in the command line as -?-.
  3754.  
  3755.                                 Configuration
  3756.                                 -------------
  3757.  
  3758.    The program can be configured using a configuration file named poly3d-r.cfg.
  3759.    This is a plain ASCII file you can edit directly and set the parameters
  3760.  according to the comments there. 'poly3d-r -z' will display the current
  3761.  configuration as read from the configuration file.
  3762.  
  3763.    The configuration file is searched in the directory specified by the
  3764.  IRIT_PATH environment variable. For example
  3765.  'setenv IRIT_PATH /u/gershon/irit/bin/'.
  3766.    If the IRIT_PATH variable is not set, the current directory is searched.
  3767.  
  3768.                                     Usage
  3769.                                     -----
  3770.  
  3771.    As this program is not interactive, usage is quite simple, and the only
  3772.  control available is using the command lines options.
  3773.  
  3774.    Some Remarks:
  3775.  
  3776.   1. If the input file is degenerate (2 vertices are identical, etc.), the
  3777.      degenerate data will be ignored in the next passes. Use [-m] if you want
  3778.      to know about them.
  3779.  
  3780.   2. The color of the object can be extracted via the COLOR attribute as set
  3781.      via the IRIT COLOR command. In addition to this fixed set of colors, one
  3782.      can specify the color in RGB space using the ATTRIB command.
  3783.  
  3784.  Example:
  3785.  
  3786.      attrib( Srf17, "rgb", "255,155,55" );
  3787.  
  3788.      Each of R G B must be an integer in the range [0..255].
  3789.  
  3790.                  Illustrt - Simple line illustration filter
  3791.                  ------------------------------------------
  3792.  
  3793.  
  3794.                                 Introduction
  3795.                                 ------------
  3796.  
  3797.  illustrt is a filter that processes IRIT data files and dumps out modified
  3798.  IRIT data files. illustrt can be used to make simple nice illustrations of
  3799.  data. The features of illustrt include depth sorting, hidden line clipping 
  3800.  at intersection points, and vertex enhancements. illustrt is designed to
  3801.  closely interact with irit2ps, although it is not neceessary to use irit2ps
  3802.  on illustrt output.
  3803.  
  3804.                             Command line options
  3805.                             --------------------
  3806.  
  3807.    illustrt [-I #IsoLines] [-S #SampPerCrv] [-s] [-M] [-P] [-p]
  3808.             [-l MaxLnLen] [-a] [-t TrimInter] [-o OutName] [-T] [-z] DFiles
  3809.  
  3810.   -I #IsoLines: Specifies number of isolines per surface, per direction.
  3811.   -S #SampPerCrv: Specifies the log based 2 of number of samples per
  3812.         (iso)curve.
  3813.   -s: sorts the data in Z depth order that emulates hidden line removal
  3814.         once the data are drawn.
  3815.   -M: Dumps the control mesh/polygon as well.
  3816.   -P: Dumps the curve/surface as isocurves.
  3817.   -p: Dumps vertices of polygons/lines as points.
  3818.   -l MaxLnLen: breaks long lines into shorter ones with maximal length
  3819.         of MaxLnLen. This option is necessary to achieve good depth depending
  3820.         line width in the '-d' option of irit2ps.
  3821.   -a: takes into account the angle between the two (poly)lines that
  3822.         intersect when computing how much to trim. See also -t.
  3823.   -t TrimInter: Each time two (poly)line segments intersect in the
  3824.         projection plane, the (poly)line that is farther away from the
  3825.         viewer is clipped TrimInter amount from both sides. See also -a.
  3826.   -o OutName: Name of output file. Default is stdout.
  3827.   -T: Talkative mode. Prints processing information.
  3828.   -z: Prints version number and current defaults.
  3829.  
  3830.                                     Usage
  3831.                                     -----
  3832.  
  3833.     illustrt is a simple line illustration tool. It process geometry such
  3834.  as polylines and surfaces and dumps geometry with attributes that will make
  3835.  nice line illustrations. illustrt is geared mainly toward its use with
  3836.  irit2ps to create postscript illustrations. Here is a simple example:
  3837.  
  3838.  illustrt -s -l 0.1 solid1.dat | irit2ps -W 0.05 -d 0.2 0.6 -u - > solid.ps
  3839.  
  3840.  make sure all segments piped into irit2ps are shorter than 0.1 and sort them
  3841.  in order to make sure hidden surface removal is correctly applied. Irit2ps
  3842.  is invoked with depth cueing activated, and a default width of 0.05.
  3843.  
  3844.     illustrt dumps out regular IRIT data files, so output can be handled
  3845.  like any other data set. illustrt does the following processing to the input
  3846.  data set:
  3847.  
  3848.   Converts surfaces to isocurves ('-I' flag) and isocurves and curves to
  3849.   polylines ('-S' flag), and converts polygons to polylines.
  3850.     Polygonal objects are considered closed and even though each edge is
  3851.   shared by two polygons, only a single one is generated.
  3852.   Finds the intersection location in the projection plane of all segments in
  3853.   the input data set and trims away the far segment at both sides of the
  3854.   intersection point by an amount controlled by the '-t' and '-a' flags.
  3855.   Breaks polylines and long lines into short segments, as specified via the
  3856.   '-l' flag, so that width depth cueing can be applied more accurately
  3857.   (see irit2ps's '-d' flag) as well as the Z sorting.
  3858.   Generates vertices of polygons in the input data set as points in output data
  3859.   controlled via the '-p' flag.
  3860.   set.
  3861.   Applies a Z sort to the output data, if '-s', so drawing in order of the data
  3862.   will produce a properly hidden surface removal drawing.
  3863.  
  3864.  Here is a more complex example. Make sure tubular is properly set via
  3865.  "attrib(solid1, "tubular", 0.7);" and invoke:
  3866.  
  3867.  illustrt -s -p -l 0.1 -t 0.05 solid1.dat |
  3868.      irit2ps -W 0.05 -d 0.2 0.6 -p h 0.05 -u - > solid.ps
  3869.  
  3870.  makes sure all segments piped into irit2ps are shorter than 0.1, generates
  3871.  points for the vertices, sorts the data in order to make sure hidden surface
  3872.  removal is correctly applied, and trims the far edge by 0.05 at an
  3873.  intersection point. Irit2ps is invoked with depth cueing activated and a
  3874.  default width of 0.05, points are drawn as hollowed circles of default
  3875.  size 0.05, and lines are drawn tubular.
  3876.  
  3877.                      DAT2IRIT - Data To IRIT file filter
  3878.                      -----------------------------------
  3879.  
  3880.                             Command line options
  3881.                             --------------------
  3882.  
  3883.    dat2irit [-z] DFiles
  3884.  
  3885.   -z: Print version number and current defaults.
  3886.  
  3887.                                     Usage
  3888.                                     -----
  3889.  
  3890.     It may be sometimes desired to convert .dat data files into a form that
  3891.  can be fed back to IRIT - a '.irt' file. This filter does exactly that.
  3892.  
  3893.  Example:
  3894.  
  3895.    dat2irit b58.dat > b58-new.irt
  3896.  
  3897.                    DXF2IRIT - DXF (Autocad) To IRIT filter
  3898.                    ---------------------------------------
  3899.  
  3900.    Due to lack of real documentation on the DXF format (for surfaces), this
  3901.  filter is not really complete. It only work for polygons, and is provided
  3902.  here only for those desperate enough to try and fix it...
  3903.  
  3904.                    IRIT2DXF - IRIT To DXF (Autocad) filter
  3905.                    ---------------------------------------
  3906.  
  3907.    Due to lack of real documentation on the DXF format (for surfaces), this
  3908.  filter is not really complete. It works only for polygons, and is provided
  3909.  here only for those desperate enough to try and fix it...
  3910.  
  3911.                         IRIT2NFF - IRIT To NFF filter
  3912.                         -----------------------------
  3913.  
  3914.                             Command line options
  3915.                             --------------------
  3916.  
  3917.   irit2nff [-l] [-4] [-c] [-f FineNess] [-o OutName] [-T] [-g] [-z] DFiles
  3918.  
  3919.   -l: Linear - forces linear (degree two) surfaces to be approximated
  3920.        by a single polygon along their linear direction.
  3921.        Although, most of the time, linear direction can be exactly represented
  3922.        using a single polygon, even a bilinear surface can have a free-form
  3923.        shape (saddle-like) that is not representable using a single polygon.
  3924.        Note that although this option will better emulate the surface shape,
  3925.        it will create unnecessary polygons in cases where one is enough.
  3926.   -4: Four - Generates four polygons per flat patch. Default is 2.
  3927.   -c: Output files should be filtered by cpp. When set, the usually
  3928.        huge geometry file is separated from the main nff file that contains
  3929.        the surface properties and view parameters. By default all data,
  3930.        including the geometry, are saved into a single file with type extension
  3931.        '.nff'. Use of '-c' will pull out all the geometry into a file with
  3932.        the same name but a '.geom' extension, which will be included using the
  3933.        '#include' command. The '.nff' file should, in that case, be
  3934.        preprocessed using cpp before being piped into the nff renderer.
  3935.   -f FineNess: An integer value controlling the fineness of surface to
  3936.        polygons process. Roughly speaking, it sets the number of polygons
  3937.        along one Bezier patch direction. A Bezier patch will have order of
  3938.        FineNess^2 polygons then. The order of the surface also affects the
  3939.        amount of polygons; the higher the order is, the more polygons are
  3940.        created. A Bspline surface is first converted into piecewise Bezier
  3941.        to make sure C1 discontinuities will show up in the polygonal
  3942.        approximation.
  3943.   -o OutName: Name of output file. By default the name of the first data
  3944.        file from the DFiles list is used.  See below on the output files.
  3945.   -g: Generates the geometry file only. See below.
  3946.   -T: Talkative mode. Prints processing information.
  3947.   -z: Prints version number and current defaults.
  3948.  
  3949.                                     Usage
  3950.                                     -----
  3951.  
  3952.     Irit2Nff converts freeform surfaces into polygons in a format that can
  3953.  be used by an NFF renderer. Usually, one file is created with '.nff' type
  3954.  extension. Since the number of polygons can be extremely large, a '-c'
  3955.  option is provided, which separates the geometry from the surface
  3956.  properties and view specification, but requires preprocessing by cpp.
  3957.  The geometry is isolated in a file with extension '.geom' and included
  3958.  (via '#include') in the main '.nff' file. The latter holds the surface
  3959.  properties for all the geometry as well as the viewing specification.
  3960.  This allows for the changing of shading or the viewing properties while
  3961.  editing small ('.nff') files.
  3962.  
  3963.     If '-g' is specified, only the '.geom' file is created, preserving the
  3964.  current '.nff' file. The '-g' flag can be specified only with '-c'.
  3965.  
  3966.     In practice, it may be useful to create a low resolution approximation
  3967.  of the model, change viewing/shading parameters in the '.nff' file until
  3968.  a good view and/or surface quality is found, and then run Irit2Nff once more
  3969.  to create a high resolution approximation of the geometry using '-g'.
  3970.  
  3971.  Example:
  3972.  
  3973.  irit2nff -c -l -f 5 b58.dat
  3974.  
  3975.  creates b58.nff and b58.geom with low resolution (FineNess of 5).
  3976.  
  3977.  Once done with parameter setting, a fine approximation of the model can
  3978.  be created with:
  3979.  
  3980.  irit2nff -c -l -g -f 25 b58.dat
  3981.  
  3982.  which will only recreate b58.geom (because of the -g option).
  3983.  
  3984.  One can overwrite the viewing matrix by appending a new matrix in the
  3985.  end of the command line, created by a display device:
  3986.  
  3987.  xgldrvs b58.dat
  3988.  irit2nff -l -f 5 b58.dat irit.mat
  3989.  
  3990.  where irit.mat is the viewing matrix created by xgldrvs.
  3991.  
  3992.                                Advanced Usage
  3993.                                --------------
  3994.  
  3995.    One can specify surface qualities for individual surfaces of a model.
  3996.  Several such attributes are supported by Irit2Nff and can be set within
  3997.  IRIT. See also the ATTRIB IRIT command.
  3998.  
  3999.    If a certain surface should be finer than the rest of the scene, one can
  4000.  set a "resolution" attribute which specifies the relative FineNess
  4001.  resolution of this specific surface.
  4002.  
  4003.  Example:
  4004.  
  4005.  attrib( srf1, "resolution", 2 );
  4006.  
  4007.  will force srf1 to have twice the default resolution, as set via the '-f'
  4008.  flag.
  4009.  
  4010.    Almost flat patches are converted to polygons. The rectangle can be
  4011.  converted into two polygons (by subdividing along one of its diagonals) or
  4012.  into four by introducing a new point at the center of the patch. This
  4013.  behavior is controlled by the '-4' flag, but can be overwritten for
  4014.  individual surfaces by setting a "twoperflat" or a "fourperflat" attribute.
  4015.  
  4016.    NFF specific properties are controlled via the following attributes:
  4017.  "kd", "ks", "shine", "trans", "index". Refer to the NFF manual for detail.
  4018.  
  4019.  Example:
  4020.  
  4021.  attrib( srf1, "kd", 0.3 );
  4022.  attrib( srf1, "shine", 30 );
  4023.  
  4024.    Surface color is controlled in two levels. If the object has an RGB
  4025.  attribute, it is used. Otherwise, a color, as set via the IRIT COLOR
  4026.  command, is used if set.
  4027.  
  4028.  Example:
  4029.  
  4030.  attrib( tankBody, "rgb", "244,164,96" );
  4031.  
  4032.                    IRIT2PLG - IRIT To PLG (REND386) filter
  4033.                    ---------------------------------------
  4034.  
  4035.  PLG is the format used by the rend386 real time renderer for the IBM PC.
  4036.  
  4037.                             Command line options
  4038.                             --------------------
  4039.  
  4040.   irit2plg [-l] [-4] [-f FineNess] [-T] [-z] DFiles
  4041.  
  4042.   -l: Linear - forces linear (degree two) surfaces to be approximated
  4043.        by a single polygon along their linear direction.
  4044.        Although, most of the time, linear direction can be exactly represented
  4045.        using a single polygon, even a bilinear surface can have a free form
  4046.        shape (saddle like) that is not representable using a single polygon.
  4047.        Note that although this option will better emulate the surface shape,
  4048.        it will create unnecessary polygons in cases where one is enough.
  4049.   -4: Four - Generates four polygons per flat patch. Default is 2.
  4050.   -f FineNess: An integer value controlling the fineness of surface to
  4051.        polygons process. Roughly speaking, it sets the number of polygons
  4052.        along one Bezier patch direction. A Bezier patch will have order of
  4053.        FineNess^2 polygons then. The order of the surface also affects the
  4054.        amount of polygons; The higher the order is, more polygons are created.
  4055.        A Bspline surface is first converted into piecewise Bezier to make
  4056.        sure C1 discontinuities will show up in the polygonal approximation.
  4057.   -T: Talkative mode. Prints processing information.
  4058.   -z: Prints version number and current defaults.
  4059.  
  4060.                                     Usage
  4061.                                     -----
  4062.  
  4063.     Irit2Plg converts freeform surfaces and polygons into polygons in a
  4064.  format that can be used by the REND386 renderer. 
  4065.   
  4066.  Example:
  4067.  
  4068.  irit2plg solid1.dat > solid1.plg
  4069.  
  4070.     Surfaces are converted to polygons with fineness control:
  4071.   
  4072.  irit2plg -f 10 - view.mat < saddle.dat > saddle.plg
  4073.  
  4074.     Note the use of '-' for stdin.
  4075.  
  4076.                          IRIT2PS - IRIT To PS filter
  4077.                          ---------------------------
  4078.  
  4079.                             Command line options
  4080.                             --------------------
  4081.  
  4082.   irit2ps [-s Size] [-I #UIso[:#VIso]] [-S #SampPerCrv] [-M] [-P]
  4083.           [-W LineWidth] [-c] [-C] [-T] [-i] [-o OutName] [-d [Zmin Zmax]]
  4084.                       [-D [Zmin Zmax]] [-p PtType PtSize][-u] [-z] DFiles
  4085.  
  4086.   -s Size: Controls the size of the postscript output in inches.
  4087.        Default is to fill the entire screen.
  4088.   -I #UIso[:#VIso]: Specifies the number of isolines per surface, per
  4089.         direction. If #VIso is not specified, #UIso is used for #VIso as
  4090.         well.
  4091.   -S #SampPerCrv: Specifies the log based 2 of number of samples per
  4092.         (iso)curve.
  4093.   -M: Dumps the control mesh/polygon as well.
  4094.   -P: Dumps the curve/surface as isocurves.
  4095.   -W #LineWidth: Sets the line drawing width in inches. Default is
  4096.         as thin as possible. This option will overwrite only those objects
  4097.         that do not have a "width" attribute. See also -d.
  4098.   -c: Creates a color postscript file.
  4099.   -C: Curve mode. Dumps freeform curves and surfaces as cubic
  4100.        Bezier curves. Higher order curves and surfaces and/or rationals are
  4101.        approximated by cubic Bezier curves. This option generates data
  4102.        files that are roughly a third of piecewise linear postscript files
  4103.        (by disabling this feature, -C-), but takes a longer time to compute.
  4104.   -T: Talkative mode. Prints processing information.
  4105.   -i: Internal edges (created by IRIT) - the default is not to
  4106.        display them, and this option will force displaying them as well.
  4107.   -o OutName: Name of output file. Default is stdout.
  4108.   -d [Zmin Zmax]: Sets the ratios between the depth cue and the width of
  4109.         the dumped data. See also -W, -p. Closer lines/points will be drawn
  4110.         wider/larger. Zmin and Zmax are optional. The object's bounding
  4111.         box is otherwise computed and used.
  4112.   -D [Zmin Zmax]: Same as -d, but depth cue the color or gray scale
  4113.         instead of width. You might need to consider the sorting option
  4114.         of the illustrt tool (-s of illustrt) for proper drawings.
  4115.         Only one of -d and -D can be used.
  4116.   -p PtType PtSize: Specifies the way points are drawn.
  4117.         PtType can be one of H, F, C for Hollow circle, Full Circle, or
  4118.         Cross. PtSize specifies the size of the point to be drawn, in inches.
  4119.         Vectors will also be drawn as points, but with an additional thin
  4120.         line to the origin. See also -d.
  4121.   -u: Forces a unit matrix transformation, i.e. no transformation.
  4122.   -z: Prints version number and current defaults.
  4123.  
  4124.                                     Usage
  4125.                                     -----
  4126.  
  4127.     Irit2Ps converts freeform surfaces and polygons into a postscript file.
  4128.   
  4129.  Example:
  4130.  
  4131.  irit2ps solid1.dat > solid1.ps
  4132.  
  4133.     Surfaces are converted to polygons with fineness control:
  4134.   
  4135.  irit2ps -S 5 -c -W 0.01 saddle.dat > saddle.ps
  4136.  
  4137.  creates a postscript file for the saddle model, in color, and with
  4138.  lines 0.01 inch thick.
  4139.  
  4140.                                Advanced Usage
  4141.                                --------------
  4142.  
  4143.    One can specify several attributes that affect the way the postscript
  4144.  file is generated. The attributes can be generated within IRIT.
  4145.  See also the ATTRIB IRIT command.
  4146.  
  4147.    If a certain object should be thinner or thicker than the rest of the scene,
  4148.  one can set a "width" attribute which specifies the line width in inches of
  4149.  this specific object.
  4150.  
  4151.  Example:
  4152.  
  4153.  attrib( srf1, "width", 0.02 );
  4154.  
  4155.  will force srf1 to have this width, instead of the default as set via the
  4156.  '-W' flag.
  4157.  
  4158.  If a (closed) object, a polygon for example, needs to be filled, a "fill"
  4159.  attribute should be set, with a value equal to the gray level desired.
  4160.  
  4161.  Example:
  4162.  
  4163.  attrib( poly, "fill", 0.5 );
  4164.  
  4165.  will fill poly with %50 gray.
  4166.  
  4167.  Dotted or dashed line effects can be created using a "dash" attribute which
  4168.  is a direct PostScript dash string. A simple form of this string is "[a b]"
  4169.  in which a is the drawing portion (black) in inches, followed by b inches
  4170.  of white space. See the postScript manual for more about the format of this
  4171.  string. Here is an example for a dotted-dash line.
  4172.  
  4173.  attrib( poly, "dash", "[0.006 0.0015 0.001 0.0015]" );
  4174.  
  4175.    Surface color is controlled (for color postscript only - see -c) in two
  4176.  levels. If the object has an RGB attribute, it is used. Otherwise, a color as
  4177.  set via the IRIT COLOR command is used.
  4178.  
  4179.  Example:
  4180.  
  4181.  attrib( Ball, "rgb", "255,0,0" );
  4182.  
  4183.     An object can be drawn as ``tubes'' instead of full lines. The ratio
  4184.  between the inner and the outer radii of the tube is provided as the
  4185.  TUBULAR attribute:
  4186.  
  4187.  attrib( final, "tubular", 0.7 );
  4188.  
  4189.                      IRIT2RAY - IRIT To RAYSHADE filter
  4190.                      ----------------------------------
  4191.  
  4192.                             Command line options
  4193.                             --------------------
  4194.  
  4195.   irit2ray [-l] [-4] [-G GridSize] [-f FineNess] [-o OutName] [-g]
  4196.     [-p Zmin Zmax] [-P] [-M] [-T] [-I #UIso[:#VIso]] [-S #SampPerCrv]
  4197.                                                             [-z] DFiles
  4198.  
  4199.   -l: Linear - forces linear (degree two) surfaces to be approximated
  4200.        by a single polygon along their linear direction.
  4201.          Although most of the time, linear direction can be exactly represented
  4202.        using a single polygon, even a bilinear surface can have a free-form
  4203.        shape (saddle-like) that is not representable using a single polygon.
  4204.          Note that although this option will better emulate the surface shape,
  4205.        it will create unnecessary polygons in cases where one is enough.
  4206.   -4: Four - Generates four polygons per flat patch. Default is 2.
  4207.   -G GridSize: Usually objects are grouped as lists of polygons.
  4208.        This flags will coerce the usage of the RAYSHADE grid structure,
  4209.        with GridSize being used as the grid size along the object
  4210.        bounding box's largest dimension.
  4211.   -f FineNess: An integer value controlling the fineness of surface to
  4212.        polygons process. Roughly speaking, it will be set to the number of
  4213.        polygons along one Bezier patch direction. A Bezier patch will have
  4214.        order of FineNess^2 polygons then. The order of the surface also
  4215.        affects the amount of polygons; The higher the order is, the more
  4216.        polygons are created. A Bspline surface is first converted into
  4217.        piecewise Bezier to make sure C1 discontinuities will show up in
  4218.        the polygonal approximation.
  4219.   -o OutName: Name of output file. By default the name of the first data
  4220.        file from the DFiles list is used.  See below on the output files.
  4221.   -g: Generates the geometry file only. See below.
  4222.   -p Zmin Zmax: Sets the ratios between the depth cue and the width of
  4223.        the dumped polylines. See also -P. Closer lines will be drawn
  4224.        wider.
  4225.   -P: Forces dumping polygons as polylines with thickness controlled
  4226.        by -p.
  4227.   -M: If -P (see -P and -p) then converts the control mesh/polygon
  4228.        to polylines which are represented as a sequence of truncated
  4229.        cones.
  4230.   -T: Talkative mode. Prints processing information.
  4231.   -I #UIso[:#VIso]: Specifies the number of isolines per surface, per
  4232.        direction. If #VIso is not specified, #UIso is used for #VIso as
  4233.        well.
  4234.   -S #SampPerCrv: Specifies the log based 2 of the number of samples per
  4235.        (iso)curve.
  4236.   -z: Prints version number and current defaults.
  4237.  
  4238.                                     Usage
  4239.                                     -----
  4240.  
  4241.     Irit2Ray converts freeform surfaces into polygons in a format that can
  4242.  be used by RAYSHADE. Two files are created, one with a '.geom' extension and
  4243.  one with '.ray'. Since the number of polygons can be extremely large,
  4244.  the geometry is isolated in the '.geom' file and is included
  4245.  (via '#include') in the main '.ray' file. The latter holds the surface
  4246.  properties for all the geometry as well as viewing and RAYSHADE specific
  4247.  commands. This allows for the changing of the shading or the viewing
  4248.  properties while editing small ('.ray') files.
  4249.  
  4250.     If '-g' is specified, only the '.geom' file is created, preserving the
  4251.  current '.ray' file.
  4252.  
  4253.     In practice, it may be useful to create a low resolution approximation
  4254.  of the model, change the viewing/shading parameters in the '.ray' file until
  4255.  a good view and/or surface quality is found, and then run Irit2Ray once more
  4256.  to create a high resolution approximation of the geometry using '-g'.
  4257.  
  4258.  Example:
  4259.  
  4260.  irit2ray -l -f 5 b58.dat
  4261.  
  4262.  creates b58.ray and b58.geom with low resolution (FineNess of 5).
  4263.    At such low resolution it can very well may happen that triangles will have
  4264.  normals "over the edge" since a single polygon may approximate a highly
  4265.  curved surface. That will cause RAYSHADE to issue an
  4266.  "Inconsistent triangle normals" warning. This problem will not exist if
  4267.  high fineness is used.
  4268.    One can ray trace this scene using a command similar to:
  4269.  
  4270.  RAYSHADE -p -W 256 256 b58.ray > b58.rle
  4271.  
  4272.  Once done with parameter setting for RAYSHADE, a fine approximation of the
  4273.  model can be created with:
  4274.  
  4275.  irit2ray -l -g -f 25 b58.dat
  4276.  
  4277.  which will only recreate b58.geom (because of the -g option).
  4278.  
  4279.  Interesting effects can be created using the depth cue support and polyline
  4280.  conversion of irit2ray. For example
  4281.  
  4282.  irit2ray -G 5 -P -p -0.0 0.5 solid1.dat
  4283.  
  4284.  will dump solid1 as a set of polylines (represented as truncated cones in
  4285.  RAYSHADE) with varying thickness according to the z depth. Another example
  4286.  is
  4287.  
  4288.  irit2ray -G 5 -P -p -0.1 1.0 saddle.dat
  4289.  
  4290.  which dumps the isolines extracted from the saddle surface with varying
  4291.  thickness.
  4292.  
  4293.    Each time a data file is saved in IRIT, it can be saved with the
  4294.  viewing matrix of the last INTERACT by saving the VIEW_MAT object as well.
  4295.  I.e.:
  4296.  
  4297.  save( "b58", b58 );
  4298.  
  4299.    However one can overwrite the viewing matrix by appending a new matrix
  4300.  in the end of the command line, created by the display devices:
  4301.  
  4302.  os2drvs b58.dat
  4303.  irit2ray -l -f 5 b58.dat irit.mat
  4304.  
  4305.  where irit.mat is the viewing matrix created by os2drvs. The output name,
  4306.  by default, is the last input file name, so you might want to provide an
  4307.  explicit name with the -o flag.
  4308.  
  4309.                                Advanced Usage
  4310.                                --------------
  4311.  
  4312.    One can specify surface qualities for individual surfaces of a model.
  4313.  Several such attributes are supported by Irit2Ray and can be set within
  4314.  IRIT. See also the ATTRIB IRIT command.
  4315.  
  4316.    If a certain surface should be finer than the rest of the scene, one can
  4317.  set a "resolution" attribute which specifies the relative FineNess
  4318.  resolution of this specific surface.
  4319.  
  4320.  Example:
  4321.  
  4322.  attrib( srf1, "resolution", 2 );
  4323.  
  4324.  will force srf1 to have twice the default resolution, as set via the '-f'
  4325.  flag.
  4326.  
  4327.    Almost flat patches are converted to polygons. The rectangle can be
  4328.  converted into two polygons (by subdividing along one of its diagonals) or
  4329.  into four by introducing a new point at the patch center. This behavior is
  4330.  controlled by the '-4' flag, but can be overwritten for individual surfaces
  4331.  bu setting "twoperflat" or "fourperflat".
  4332.  
  4333.    RAYSHADE specific properties are controlled via the following attributes:
  4334.  "specpow", "reflect", "transp", "body", "index", and "texture". Refer to
  4335.  RAYSHADE manual for their meaning.
  4336.  
  4337.   Example:
  4338.  
  4339.  attrib( srf1, "transp", 0.3 );
  4340.  attrib( srf1, "texture", "wood" );
  4341.  
  4342.    Surface color is controlled in two levels. If the object has an RGB
  4343.  attribute, it is used. Otherwise a color as set via the IRIT COLOR
  4344.  command is being used if set.
  4345.  
  4346.  Example:
  4347.  
  4348.  attrib( tankBody, "rgb", "244,164,96" );
  4349.  
  4350.                   IRIT2Scn - IRIT To SCENE (RTrace) filter
  4351.                   ----------------------------------------
  4352.  
  4353.  SCENE is the format used by the RTrace ray tracer. This filter was donated
  4354.  by Antonio Costa (acc@asterix.inescn.pt), the author of RTrace.
  4355.  
  4356.                             Command line options
  4357.                             --------------------
  4358.  
  4359.   irit2scn [-l] [-4] [-f FineNess] [-o OutName] [-g] [-T] [-z] DFiles
  4360.  
  4361.   -l: Linear - forces linear (degree two) surfaces to be approximated
  4362.        as a single polygon along their linear direction.
  4363.          Although most of the time, linear direction can be exactly represented
  4364.        using a single polygon, even a bilinear surface can have a free-form
  4365.        shape (saddle-like) that is not representable using a single polygon.
  4366.          Note that although this option will better emulate the surface shape,
  4367.        it will create unnecessary polygons in cases where one is enough.
  4368.   -4: Four - Generates four polygons per flat patch.
  4369.   -f FineNess: An integer value controlling the fineness of surface to
  4370.        polygons process. Roughly speaking, it will be set to the number of
  4371.        polygons along one Bezier patch direction. A Bezier patch will have
  4372.        order of FineNess^2 polygons then. The order of the surface also
  4373.        affects the amount of polygons; The higher the order is, the more
  4374.        polygons are created. A Bspline surface is first converted into
  4375.        piecewise Bezier to make sure C1 discontinuities will show up in
  4376.        the polygonal approximation.
  4377.   -o OutName: Name of output file. By default the name of the first data
  4378.        file from DFiles list is used.  See below on the output files.
  4379.   -g: Generates the geometry file only. See below.
  4380.   -T: Talkative mode. Prints processing information.
  4381.   -z: Prints version number and current defaults.
  4382.  
  4383.                                     Usage
  4384.                                     -----
  4385.  
  4386.     Irit2Scn converts freeform surfaces and polygons into polygons in a format
  4387.  that can be used by RTrace. Two files are created, one with a '.geom'
  4388.  extension and one with '.scn'. Since the number of polygons can be extremely
  4389.  large, the geometry is isolated in the '.geom' file and is included
  4390.  (via '#include') in the main '.scn' file. The latter holds the surface
  4391.  properties for all the geometry as well as viewing and RTrace specific
  4392.  commands. This allows for the changing of the shading or the viewing
  4393.  properties while editing small ('.scn') files.
  4394.  
  4395.     If '-g' is specified, only the '.geom' file is created, preserving the
  4396.  current '.scn' file.
  4397.  
  4398.     In practice, it may be useful to create a low resolution approximation
  4399.  of the model, change the viewing/shading parameters in the '.scn' file
  4400.  until a good view and/or surface quality is found, and then run Irit2Scn once
  4401.  more to create a high resolution approximation of the geometry using '-g'.
  4402.  
  4403.  Example:
  4404.  
  4405.  irit2scn -l -f 5 b58.dat
  4406.  
  4407.  creates b58.scn and b58.geom with low resolution (FineNess of 5).
  4408.  
  4409.    One can ray trace this scene after converting the scn file to a sff file,
  4410.  using scn2sff provided with the RTrace package.
  4411.  
  4412.  Once done with the parameter setting of RTrace, a fine approximation of the
  4413.  model can be created with:
  4414.  
  4415.  irit2scn -l -g -f 25 b58.dat
  4416.  
  4417.  which will only recreate b58.geom (because of the -g option).
  4418.  
  4419.    One can overwrite the viewing matrix by appending a new matrix
  4420.  in the end of the command line, created by the display devices:
  4421.  
  4422.  wntdrvs b58.dat
  4423.  irit2scn -l -f 5 b58.dat irit.mat
  4424.  
  4425.  where irit.mat is the viewing matrix created by wntdrvs. The output name,
  4426.  by default, is the last input file name, so you might want to provide an
  4427.  explicit name with the -o flag.
  4428.  
  4429.                                Advanced Usage
  4430.                                --------------
  4431.  
  4432.    One can specify surface qualities for individual surfaces of a model.
  4433.  Several such attributes are supported by Irit2Scn and can be set within 
  4434.  IRIT. See also the ATTRIB IRIT command.
  4435.  
  4436.    If a certain surface should be finer than the rest of the scene, one can
  4437.  set a "resolution" attribute which specifies the relative FineNess
  4438.  resolution of this specific surface.
  4439.  
  4440.  Example:
  4441.  
  4442.  attrib( srf1, "resolution", 2 );
  4443.  
  4444.  will force srf1 to have twice the default resolution, as set via the '-f'
  4445.  flag.
  4446.  
  4447.    Almost flat patches are converted to polygons. The patch can be converted
  4448.  into two polygons (by subdividing along one of its diagonals) or into four
  4449.  by introducing a new point at the patch center. This behavior is controlled
  4450.  by the '-4' flag, but can be overwritten for individual surfaces bu setting
  4451.  "twoperflat" or "fourperflat".
  4452.  
  4453.    RTrace specific properties are controlled via the following attributes:
  4454.  "SCNrefraction", "SCNtexture", "SCNsurface. Refer to the RTrace manual for
  4455.  their meaning.
  4456.  
  4457.  Example:
  4458.  
  4459.  attrib( srf1, "SCNrefraction", 0.3 );
  4460.  
  4461.    Surface color is controlled in two levels. If the object has an RGB
  4462.  attribute, it is used. Otherwise a color as set via IRIT COLOR command
  4463.  is used if set.
  4464.  
  4465.  Example:
  4466.  
  4467.  attrib( tankBody, "rgb", "244,164,96" );
  4468.  
  4469.                        IRIT2Xfg - IRIT To XFIG filter
  4470.                        ------------------------------
  4471.  
  4472.                             Command line options
  4473.                             --------------------
  4474.  
  4475.   irit2xfg [-s Size] [-t XTrans YTrans] [-I #UIso[:#VIso]] [-S #SampPerCrv]
  4476.                                [-M] [-P] [-T] [-i] [-o OutName] [-z] DFiles
  4477.  
  4478.   -s Size: Size in inches of the page. Default is 7 inches.
  4479.   -t XTrans YTrans: X and Y translation. of the image. Default is (0, 0).
  4480.   -I #UIso[:#VIso]: Specifies the number of isolines per surface, per
  4481.         direction. If #VIso is not specified, #UIso is used for #VIso as
  4482.         well.
  4483.   -S #SampPerCrv: Specifies the log based 2 of number of samples per
  4484.         (iso)curve.
  4485.   -M: Dumps the control mesh/polygon as well.
  4486.   -P: Dumps the curve/surface as isocurves.
  4487.   -T: Talkative mode. Prints processing information.
  4488.   -i: Internal edges (created by IRIT) - default is not to
  4489.        display them, and this option will force displaying them as well.
  4490.   -o OutName: Name of output file. By default the name of the first data
  4491.        file from DFiles list is used.  See below on the output files.
  4492.   -z: Prints version number and current defaults.
  4493.  
  4494.                                     Usage
  4495.                                     -----
  4496.  
  4497.     Irit2Xfg converts freeform surfaces and polygons into polylines in a format
  4498.  that can be used by XFIG.
  4499.   
  4500.  Example:
  4501.  
  4502.  irit2Xfg -l -f 15 saddle.dat > saddle.xfg
  4503.  
  4504.    However, one can overwrite the viewing matrix by appending a new matrix
  4505.  in the end of the command line, created by the display devices:
  4506.  
  4507.  x11drvs b58.dat
  4508.  irit2Xfg -l -f 5 b58.dat irit.mat > saddle.xfg
  4509.  
  4510.  where irit.mat is the viewing matrix created by x11drvs.
  4511.  
  4512.                                DATAFILE Format
  4513.                                ---------------
  4514.  
  4515.    This section describes the data file format used to exchange data between
  4516.  IRIT and its accompanying tools.
  4517.  
  4518.  [OBJECT {ATTRS} OBJNAME
  4519.      [NUMBER n]
  4520.  
  4521.    | [VECTOR x y z]
  4522.  
  4523.    | [CTLPT POINT_TYPE {w} x y {z}]
  4524.  
  4525.    | [STRING "a string"]
  4526.  
  4527.    | [MATRIX m00 ... m03
  4528.              m10 ... m13
  4529.              m20 ... m23
  4530.              m30 ... m33]
  4531.  
  4532.      ;A polyline should be drawn from first point to last. Nothing is drawn
  4533.      ;from last to first (in a closed polyline, last point is equal to first).
  4534.    | [POLYLINE {ATTRS} #PTS                   ;#PTS = number of points.
  4535.          [{ATTRS} x y z]
  4536.          [{ATTRS} x y z]
  4537.             .
  4538.             .
  4539.             .
  4540.          [{ATTRS} x y z]
  4541.      ]
  4542.  
  4543.      ;Defines a closed planar region. Last point is NOT equal to first,
  4544.      ;and a line from last point to first should be drawn when the boundary
  4545.      ;of the polygon is drawn.
  4546.    | [POLYGON {ATTRS} #PTS
  4547.          [{ATTRS} x y z]
  4548.          [{ATTRS} x y z]
  4549.             .
  4550.             .
  4551.             .
  4552.          [{ATTRS} x y z]
  4553.      ]
  4554.  
  4555.      ;Defines a "cloud" of points.
  4556.    | [POINTLIST {ATTRS} #PTS
  4557.          [{ATTRS} x y z]
  4558.          [{ATTRS} x y z]
  4559.             .
  4560.             .
  4561.             .
  4562.          [{ATTRS} x y z]
  4563.      ]
  4564.  
  4565.      ;Defines a Bezier curve with #PTS control points. If the curve is
  4566.      ;rational, the rational component is introduced first.
  4567.    | [CURVE BEZIER {ATTRS} #PTS POINT_TYPE
  4568.          [{ATTRS} {w} x y z ...]
  4569.          [{ATTRS} {w} x y z ...]
  4570.             .
  4571.             .
  4572.             .
  4573.          [{ATTRS} {w} x y z ...]
  4574.      ]
  4575.  
  4576.      ;Defines a Bezier surface with #UPTS * #VPTS control points. If the
  4577.      ;surface is rational, the rational component is introduced first.
  4578.      ;Points are printed row after row (#UPTS per row), #VPTS rows.
  4579.    | [SURFACE BEZIER {ATTRS} #UPTS #VPTS POINT_TYPE
  4580.          [{ATTRS} {w} x y z ...]
  4581.          [{ATTRS} {w} x y z ...]
  4582.             .
  4583.             .
  4584.             .
  4585.          [{ATTRS} {w} x y z ...]
  4586.      ]
  4587.  
  4588.      ;Defines a Bspline curve of order ORDER with #PTS control points. If the
  4589.      ;curve is rational, the rational component is introduced first.
  4590.      ;Note length of knot vector is equal to #PTS + ORDER.
  4591.    | [CURVE BSPLINE {ATTRS} #PTS ORDER POINT_TYPE
  4592.          [KV {ATTRS} kv0 kv1 kv2 ...]                    ;Knot vector
  4593.          [{ATTRS} {w} x y z ...]
  4594.          [{ATTRS} {w} x y z ...]
  4595.             .
  4596.             .
  4597.             .
  4598.          [{ATTRS} {w} x y z ...]
  4599.      ]
  4600.  
  4601.      ;Defines a Bspline surface with #UPTS * #VPTS control points, of order
  4602.      ;UORDER by VORDER. If the surface is rational, the rational component
  4603.      ;is introduced first.
  4604.      ;Points are printed row after row (#UPTS per row), #VPTS rows.
  4605.    | [SURFACE BSPLINE {ATTRS} #UPTS #VPTS UORDER VORDER POINT_TYPE
  4606.          [KV {ATTRS} kv0 kv1 kv2 ...]                ;U Knot vector
  4607.          [KV {ATTRS} kv0 kv1 kv2 ...]                ;V Knot vector
  4608.          [{ATTRS} {w} x y z ...]
  4609.          [{ATTRS} {w} x y z ...]
  4610.             .
  4611.             .
  4612.             .
  4613.          [{ATTRS} {w} x y z ...]
  4614.      ]
  4615.  ]
  4616.  
  4617.  POINT_TYPE -> E1 | E2 | E3 | E4 | E5 | P1 | P2 | P3 | P4 | P5
  4618.  
  4619.  ATTRS -> [ATTRNAME ATTRVALUE]
  4620.           | [ATTRNAME]
  4621.           | [ATTRNAME ATTRVALUE] ATTRS
  4622.  
  4623.  
  4624.  Some notes:
  4625.  
  4626.  * This definition for the text file is designed to minimize the
  4627.    reading time and space. All information can be read without backward
  4628.    or forward referencing.
  4629.  
  4630.  * An OBJECT must not hold different geometry or other entities.
  4631.    I.e. CURVEs, SURFACEs, and POLYGONs must all be in different OBJECTs.
  4632.  
  4633.  * Attributes should be ignored if not needed. The attribute list may have
  4634.    any length and is always terminated by a token that is NOT 'verb+[+'. This
  4635.    simplifies and disambiguates the parsing.
  4636.  
  4637.  * Comments may appear between 'verb+[+OBJECT ...verb+]+' blocks, or
  4638.    immediately after OBJECT OBJNAME, and only there.
  4639.  
  4640.    A comment body can be anything not containing the 'verb+[+' or the
  4641.    'verb+]+' tokens (signals start/end of block). Some of the comments in
  4642.    the above definition are illegal and appear there only of the sake
  4643.    of clarity.
  4644.  
  4645.  * It is preferred that geometric attributes such as NORNALs will be saved in
  4646.    the geometry structure level (POLYGON, CURVE or vertices) while graphical
  4647.    and others such as COLORs will be saved in the OBJECT level.
  4648.  
  4649.  * Objects may be contained in other objects to an arbitrary level.
  4650.  
  4651.  Here is an example that exercises most of the data format:
  4652.  
  4653.  This is a legal comment in a data file.
  4654.  [OBJECT DEMO
  4655.      [OBJECT REAL_NUM
  4656.          And this is also a legal comment.
  4657.          [NUMBER 4]
  4658.      ]
  4659.  
  4660.      [OBJECT A_VECTOR
  4661.          [VECTOR 1 2 3]
  4662.      ]
  4663.  
  4664.      [OBJECT CTL_POINT
  4665.          [CTLPT E3 1 2 3]
  4666.      ]
  4667.  
  4668.      [OBJECT STR_OBJ
  4669.          [STRING "string"]
  4670.      ]
  4671.  
  4672.      [OBJECT UNIT_MAT
  4673.          [MATRIX
  4674.             1 0 0 0
  4675.             0 1 0 0
  4676.             0 0 1 0
  4677.             0 0 0 1
  4678.          ]
  4679.      ]
  4680.  
  4681.      [OBJECT [COLOR 4] POLY1OBJ
  4682.          [POLYGON [PLANE 1 0 0 0.5] 4
  4683.              [-0.5 0.5 0.5]
  4684.              [-0.5 -0.5 0.5]
  4685.              [-0.5 -0.5 -0.5]
  4686.              [-0.5 0.5 -0.5]
  4687.          ]
  4688.          [POLYGON [PLANE 0 -1 0 0.5] 4
  4689.              [0.5 0.5 0.5]
  4690.              [-0.5 0.5 0.5]
  4691.              [-0.5 0.5 -0.5]
  4692.              [0.5 0.5 -0.5]
  4693.          ]
  4694.      ]
  4695.  
  4696.      [OBJECT [COLOR 63] ACURVE
  4697.          [CURVE BSPLINE 16 4 E2
  4698.              [KV 0 0 0 0 1 1 1 2 3 4 5 6 7 8 9 10 11 11 11 11]
  4699.              [0.874 0]
  4700.              [0.899333 0.0253333]
  4701.              [0.924667 0.0506667]
  4702.              [0.95 0.076]
  4703.              [0.95 0.76]
  4704.              [0.304 1.52]
  4705.              [0.304 1.9]
  4706.              [0.494 2.09]
  4707.              [0.722 2.242]
  4708.              [0.722 2.318]
  4709.              [0.38 2.508]
  4710.              [0.418 2.698]
  4711.              [0.57 2.812]
  4712.              [0.57 3.42]
  4713.              [0.19 3.572]
  4714.              [0 3.572]
  4715.          ]
  4716.      ]
  4717.  
  4718.      [OBJECT [COLOR 2] SOMESRF
  4719.          [SURFACE BEZIER 3 3 E3
  4720.              [0 0 0]
  4721.              [0.05 0.2 0.1]
  4722.              [0.1 0.05 0.2]
  4723.  
  4724.              [0.1 -0.2 0]
  4725.              [0.15 0.05 0.1]
  4726.              [0.2 -0.1 0.2]
  4727.  
  4728.              [0.2 0 0]
  4729.              [0.25 0.2 0.1]
  4730.              [0.3 0.05 0.2]
  4731.          ]
  4732.      ]
  4733.  ]
  4734.  
  4735.                             BUGS and LIMITATIONS
  4736.                             --------------------
  4737.  
  4738.    Like any program of more than one line, it is far from being perfect.
  4739.  Some limitations, as well as simplifications, are laid out below.
  4740.  
  4741.  1. If the intersection curve of two objects falls exactly on polygon
  4742.     boundaries, for all polygons, the system will scream that the two objects
  4743.     do not intersect at all. Try to move one by EPSILON into the other.
  4744.     I probably should fix this one - it is supposed to be relatively easy.
  4745.  
  4746.  2. Avoid degenerate intersections that result with a point or a line.
  4747.     They will probably cause wrong propagation of the inner and outer part of
  4748.     one object relative to the other. Always extend your object beyond the
  4749.     other object.
  4750.  
  4751.  3. If two objects have no intersection in their boundary, IRIT assumes they
  4752.     are disjoint: a union simply combines them, and the other Boolean
  4753.     operators return a NULL object. One should find a FAST way (3D Jordan
  4754.     theorem) to find the relation between the two (A in B, B in A, A
  4755.     disjoint B) and according to that, make a decision.
  4756.  
  4757.  4. Sweep of a circular curve along a circular curve does not create an
  4758.     exact piece of a torus.
  4759.  
  4760.  5. Since the boolean sum implementation constructs ruled surfaces with
  4761.     uniform speed, it might return a somewhat incorrect answer, given
  4762.     non-uniform input curves.
  4763.  
  4764.  6. The parser is out of hand and is difficult to maintain. There are several
  4765.     memory leaks there that one should fix.
  4766.  
  4767.  7. The X11 driver has no menu support (any easy way to have menus using
  4768.     Xlib!?).
  4769.  
  4770.  8. IBM R6000 fails to run the drivers in -s- mode.
  4771.  
  4772.  9. Rayshade complains a lot about degenerate polygons on irit2ray output.
  4773.     To alleviate the problem, change the 'equal' macro in common.h in libcommon
  4774.     of rayshade from EPSILON (1e-5) to 1e-7 or even lower.
  4775.  
  4776.  
  4777.